Central de Documentação Manuais de usuário do CRTI ERP
← Central de Documentação

API REST do CRTI ERP

Autenticação, ambientes, permissões e requisitos operacionais da API pública do CRTI ERP.

A seguir será descrita a API REST do CRTI ERP, seu ciclo de vida, e como utilizá-la. O Swagger da API pública pode ser visualizado em https://[nomedocliente].crti.com.br/api, com o usuário logado no ERP. Existem 3 tipos de autenticação com o ERP: via login e senha, via chave de autenticação e via OAuth 2.0. Para novos softwares clientes do ERP, como aplicativos ou frontends, utilize a API de login e senha. Para aplicações B2B (Business to Business), utilize chave de autenticação ou OAuth 2.0.

1. Métodos de Autenticação

1.1. Chave Única (X-Api-Key)

Método de autenticação simples baseado em chave única. Recomendado para integrações B2B com outros ERPs, softwares de BI, CRM, e sistemas que necessitam de acesso contínuo sem renovação de credenciais. A chave não expira e mantém as mesmas permissões do usuário que a gerou.

1.2. Credenciais de Integração (OAuth 2.0 - client_credentials)

Método de autenticação baseado no padrão OAuth 2.0 com fluxo client_credentials. Indicado para integrações com portais web de clientes, fornecedores, e aplicações que requerem tokens de curta duração (5 minutos) com renovação automática. Oferece maior segurança por meio da expiração automática dos tokens.

1.3. Login e Senha (Request/Refresh Tokens)

Método de autenticação interativa para aplicativos de usuário final. Ideal para aplicativos móveis (smartphones/tablets), softwares desktop, e frontends customizados do ERP. Utiliza tokens de acesso de 15 minutos renováveis através de refresh tokens válidos por 1 dia.

1.1. Autenticação via Chave Única (X-Api-Key)

1.1.1. Geração da Chave

Pré-requisito: crie um usuário dedicado exclusivamente para a integração via X-Api-Key. Esse usuário deve ser configurado com a categoria de usuário específica para uso de chave de API. Não utilize usuários de pessoas físicas (colaboradores) para integrações B2B — cada integração deve possuir seu próprio usuário dedicado.

A chave é gerada por um administrador do sistema. Não é necessário estar logado com o usuário dedicado para realizar esse procedimento.

Passo a passo:

  1. Acesse Configurações do Sistema > Permissões > Usuário.
  2. Localize e edite o usuário dedicado à integração.
  3. Na tela de cadastro, clique em Credenciais B2B > Chave Única (X-Api-Key).
  4. Clique em Gerar chave e informe um nome que identifique o uso da chave (ex.: “Integração ERP–CRM”).
  5. Copie a chave imediatamente. Ela será exibida apenas uma única vez.

Importante:

  • Ao fechar a janela, a chave não poderá ser recuperada. Caso a perca, será necessário invalidá-la e gerar uma nova.
  • Armazene a chave de forma segura (ex.: cofre de senhas, variável de ambiente protegida). Evite guardá-la em arquivos de texto, planilhas ou outros meios não criptografados.

1.1.2. Utilização da Chave

Para utilizar a chave, deverá ser enviado o header X-API-Key em cada requisição, informando a chave gerada.

GET /api/v1/modelo/recurso
X-API-Key: chave_de_autenticacao

1.2. Autenticação via OAuth 2.0 (client_credentials)

1.2.1. Geração das Credenciais OAuth 2.0

O par de chaves OAuth 2.0 pode ser gerado no ERP em Configurações do Sistema > Permissões > Usuário. Edite um usuário e, na tela de cadastro, clique em Credenciais B2B > Credenciais de Integração (OAuth 2.0). Nessa tela, selecione Gerar chave e dê um nome que identifique o uso da chave. O par de chaves (client_id e client_secret) será exibido apenas uma vez. Ao fechar a janela, se necessitar das chaves novamente, será necessário invalidar e gerar um novo par. Armazene as chaves geradas de forma segura, evitando guardá-las em arquivos texto ou em meios não criptografados.

1.2.2. Obtenção do Token de Acesso

Primeiro deverá ser obtido um token de acesso (access token) utilizando o par de chaves gerado. O token de acesso tem validade de 5 minutos. Após esse período, deverá ser obtido um novo token de acesso, utilizado para autorizar as requisições à API.

O token é obtido pelo endpoint /oauth2/token, método POST, corpo application/x-www-form-urlencoded:

POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=seu_client_id&client_secret=seu_client_secret

Resposta:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 300
}

1.2.3. Utilização do Token de Acesso

Inclua o token no cabeçalho de todas as requisições subsequentes. Validade de 5 minutos (300 segundos).

GET /api/v1/modelo/recurso
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

1.2.4. Geração de Novo Token

O fluxo client_credentials não utiliza refresh tokens. Quando o access token expirar, solicite um novo token pelo mesmo endpoint /oauth2/token, com as mesmas credenciais. Recomenda-se implementar cache do token com renovação automática antes da expiração, para evitar interrupções e otimizar o desempenho.

1.3. Autenticação via Login e Senha (Request/Refresh Tokens)

A utilização da API pública REST do CRTI ERP segue um fluxo bem definido, que permite autenticação e continuidade da comunicação segura entre cliente e servidor. Siga o fluxo recomendado para o correto funcionamento e para evitar bloqueios por consumo indevido da API.

1.3.1. Autenticação Inicial (Endpoint de signin)

Utilize o endpoint signin, enviando as credenciais do usuário, para obter um request token, usado para autorizar as requisições subsequentes.

POST /api/v1/auth/signin
Content-Type: application/json
{
  "username": "seu_usuario",
  "password": "sua_senha"
}

Resposta:

{
  "accessToken": "Token de Acesso válido por 15 minutos.",
  "refreshToken": "Token de Refresh válido por 1 dia."
}

1.3.2. Utilização do Request Token

Inclua o request token no cabeçalho de todas as requisições subsequentes. Validade de 15 minutos.

GET /api/v1/modelo/recurso
Authorization: Bearer seu_request_token

1.3.3. Renovação do Token (Endpoint de Refresh Token)

Os request tokens têm validade limitada. Para evitar autenticar novamente o usuário após a expiração, use o endpoint de refresh token, obtendo um novo request token e um novo refresh token. Após o uso, o refresh token anterior é invalidado.

POST /api/v1/auth/refresh_token
Content-Type: application/json
{
  "refreshToken": "seu_refresh_token"
}

Resposta:

{
  "accessToken": "Token de Acesso válido por 15 minutos.",
  "refreshToken": "Token de Refresh válido por 1 dia."
}

1.3.4. Continuidade da Sessão

Ao receber um novo request token pelo endpoint de refresh, utilize-o para continuar acessando os recursos da API. Esse ciclo pode ser repetido enquanto o refresh token atual permanecer válido.

1.3.5. Request Tokens vs. Refresh Tokens

  • Request Tokens: curta duração, usados para autenticar cada requisição.
  • Refresh Tokens: longa duração, usados exclusivamente para obter novos request tokens.

2. Ambientes Disponíveis

2.1. Ambiente de Produção

URL Base: https://[nomedocliente].crti.com.br

Substitua [nomedocliente] pelo identificador único da empresa. Exemplo: https://construtora-abc.crti.com.br.

2.2. Ambiente de Homologação

URL Base: https://[nomedocliente].hom.crti.com.br

Ambiente destinado a testes e validações antes de implementar em produção. Exemplo: https://construtora-abc.hom.crti.com.br.

2.3. Documentação Swagger/OpenAPI

Disponível no endpoint /api de cada ambiente:

  • Produção: https://[nomedocliente].crti.com.br/api
  • Homologação: https://[nomedocliente].hom.crti.com.br/api

É necessário estar autenticado no ERP para acessar a documentação Swagger.

3. Escopo e Permissões

3.1. Lista de Endpoints Disponíveis

Todos os endpoints estão documentados no Swagger/OpenAPI (/api), incluindo métodos HTTP, parâmetros obrigatórios/opcionais, estrutura de requisições/respostas e exemplos de uso.

3.2. Níveis de Permissão

Os níveis de permissão (leitura, escrita, atualização, exclusão) são definidos pela tela de Grupo de Acesso do usuário vinculado ao meio de autenticação utilizado:

  1. Cada credencial (X-API-Key, OAuth 2.0 ou Login/Senha) está vinculada a um usuário específico.
  2. Esse usuário pertence a um ou mais Grupos de Acesso.
  3. Os Grupos de Acesso definem quais recursos e operações são permitidos.
  4. As permissões configuradas no ERP são aplicadas automaticamente às requisições da API.

Gerenciamento em: Configurações do Sistema > Permissões > Grupos de Acesso.

3.3. Restrições por IP

O CRTI ERP não possui restrições por endereço IP atualmente. As requisições podem ser feitas de qualquer origem, desde que autenticadas corretamente.

3.4. Relação entre Permissões e Recursos

  • As credenciais de API têm exatamente as mesmas permissões do usuário ao qual estão vinculadas.
  • A API não concede privilégios adicionais além dos configurados no Grupo de Acesso.
  • Todas as ações via API são auditadas e vinculadas ao usuário autenticado.

Exemplo: usuário com permissão apenas de leitura em Pedidos → API só permite GET; escrita em Clientes → API permite POST/PUT; acesso não autorizado → HTTP 403.

4. Documentação Técnica

4.1. Especificação dos Endpoints

Disponível no Swagger/OpenAPI (/api): endpoints, métodos, parâmetros (query/path/body/headers), payloads, modelos de resposta, e teste direto na interface.

4.2. Códigos de Erro e Mensagens

Código Significado
200 OK Requisição bem-sucedida
201 Created Recurso criado com sucesso
400 Bad Request Erro na sintaxe ou validação da requisição
401 Unauthorized Credenciais inválidas ou ausentes
403 Forbidden Acesso negado por falta de permissão
404 Not Found Recurso não encontrado
500 Internal Server Error Erro interno do servidor

Consulte o Swagger para detalhes específicos de cada endpoint.

4.3. Versionamento da API

Versionamento via URL: /api/v{número_versão}/recurso (ex.: /api/v1/clientes, /api/v2/clientes).

  • Breaking changes: geram nova versão da API.
  • Backward compatibility: versões anteriores continuam funcionando até serem oficialmente descontinuadas.
  • Depreciação: comunicada com antecedência.
  • Utilize sempre a versão mais recente para novos desenvolvimentos.

5. Requisitos de Segurança

5.1. Protocolo de Comunicação

Protocolo exigido: HTTPS/1.1 ou superior. HTTP puro não é suportado.

  • Protocolo: HTTPS (HTTP over TLS/SSL)
  • Versão mínima: HTTP/1.1
  • Criptografia: TLS 1.2 ou superior

5.2. Boas Práticas de Segurança

  1. Armazenamento de credenciais: nunca em código-fonte; use variáveis de ambiente ou cofres (Vault, AWS Secrets Manager); nunca em repositórios públicos.
  2. Rotação de credenciais: revogue imediatamente credenciais comprometidas; gere novas pela interface do ERP.
  3. Validação de certificados: sempre valide SSL/TLS; nunca desabilite verificação em produção.

6. Aspectos Operacionais

6.1. Limites de Requisições (Rate Limiting)

Em avaliação. Recomenda-se: uso consciente da API, cache quando apropriado, evitar loops/requisições em massa sem controle, e backoff exponencial em caso de erros. Uso inadequado pode resultar em bloqueios futuros.

6.2. Timeout de Requisições

Tempo limite: 10 segundos. Configure timeout adequado no cliente (mínimo 10s) e implemente retry com backoff exponencial.

6.3. Procedimento para Reporte de Falhas

  1. Notifique o atendimento da CRTI pelo portal.
  2. O atendimento encaminha ao setor de desenvolvimento quando necessário.
  3. Inclua: descrição do problema, endpoint e método HTTP, exemplo de requisição (sem credenciais), código de erro, data/horário e ambiente.

6.4. Contatos e Suporte Técnico

Portal de Atendimento da CRTI: abertura de chamados, acompanhamento de solicitações, base de conhecimento e documentação adicional.