API REST do CRTI ERP
Autenticação, URL de acesso, permissões e requisitos operacionais da API pública do CRTI ERP.
- 1. Métodos de Autenticação
- 1.1. Autenticação via Chave Única (X-Api-Key)
- 1.2. Autenticação via OAuth 2.0 (client_credentials)
- 1.3. Autenticação via Login e Senha (Request/Refresh Tokens)
- 2. URL de Acesso
- 3. Escopo e Permissões
- 4. Documentação Técnica
- 5. Requisitos de Segurança
- 6. Aspectos Operacionais
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 duração limitada (12 horas) 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 5 dias. Quando o usuário usa autenticação em dois fatores (2FA), ou quando a empresa a exige, o login pede também o código do aplicativo autenticador.
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:
- Acesse Configurações do Sistema > Permissões > Usuário.
- Localize e edite o usuário dedicado à integração.
- Na tela de cadastro, clique em Credenciais B2B > Chave Única (X-Api-Key).
- Clique em Gerar chave e informe um nome que identifique o uso da chave (ex.: “Integração ERP–CRM”).
- 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 12 horas, informada em segundos no campo expires_in da resposta. 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": 43199
}
1.2.3. Utilização do Token de Acesso
Inclua o token no cabeçalho de todas as requisições subsequentes. Validade de 12 horas (43.200 segundos). Use o expires_in da resposta para programar a renovação, em vez de fixar o prazo no código.
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",
"codigoSegundoFator": "123456"
}
O campo codigoSegundoFator é opcional no pedido, mas passa a ser obrigatório em dois casos:
- o usuário tem a autenticação em dois fatores cadastrada;
- a empresa exige autenticação em dois fatores de todos os usuários (campo
mfaObrigatoriodo endpointinfo, seção 1.3.2).
Informe o código de 6 dígitos que o aplicativo autenticador mostra no momento (Google Authenticator, Microsoft Authenticator ou outro), ou um dos códigos de recuperação do usuário. O cadastro do aplicativo autenticador é feito pelo próprio usuário no CRTI ERP, no navegador, em Segurança > Gerenciar MFA.
Resposta:
{
"accessToken": "Token de Acesso válido por 15 minutos.",
"refreshToken": "Token de Refresh válido por 5 dias."
}
Recusas (HTTP 401), com a causa no campo message. Nas recusas da autenticação em dois fatores, o campo motivoSegundoFator traz o motivo em formato fixo: decida por ele, e não pelo texto da mensagem.
{
"message": "Este usuário usa autenticação em dois fatores: informe o código do aplicativo autenticador.",
"success": false,
"motivoSegundoFator": "CODIGO_OBRIGATORIO"
}
| Situação | motivoSegundoFator |
O que fazer |
|---|---|---|
| Login ou senha inválidos | (ausente) | Conferir as credenciais. |
Usuário com 2FA, sem o codigoSegundoFator |
CODIGO_OBRIGATORIO |
Mostrar o campo do código e repetir o login com ele, mesmo que a empresa não exija 2FA de todos. |
| Código inválido | CODIGO_INVALIDO |
Pedir o código de novo. |
| Muitos códigos errados | BLOQUEADO |
Aguardar 15 minutos. |
| Empresa exige 2FA e o usuário ainda não cadastrou o aplicativo | CADASTRO_PELO_ERP |
O usuário cadastra o aplicativo autenticador entrando no CRTI ERP pelo navegador. |
| Código informado para usuário sem 2FA cadastrado | SEM_CADASTRO |
Repetir o login sem o código. |
1.3.2. Informações da Empresa (Endpoint de info)
Antes do login, consulte o endpoint info para saber se o endereço chamado corresponde a uma empresa do CRTI ERP e quais recursos estão liberados para ela. O endpoint é público: não exige autenticação nem credenciais. A empresa é identificada pelo endereço (https://[nomedocliente].crti.com.br).
GET /api/v1/auth/info
Resposta (HTTP 200):
{
"nomeEmpresa": "Nome da empresa",
"permiteAcessoAppCargas": true,
"permiteAcessoAppApropriacoes": false,
"crtiIaContratado": false,
"mfaObrigatorio": true
}
| Campo | Significado |
|---|---|
nomeEmpresa |
Nome da empresa cadastrada no CRTI ERP. |
permiteAcessoAppCargas |
O aplicativo CRTI Cargas está liberado para a empresa. |
permiteAcessoAppApropriacoes |
O aplicativo CRTI Apropria está liberado para a empresa. |
crtiIaContratado |
A empresa contratou o CRTI IA (conexão do ERP a assistentes de IA). |
mfaObrigatorio |
A empresa exige autenticação em dois fatores de todos os usuários. Quando true, mostre o campo do código (codigoSegundoFator) na tela de login do aplicativo. |
Quando mfaObrigatorio é false, o código continua obrigatório para quem cadastrou a autenticação em dois fatores por conta própria. Aplicativos que não mostram o campo recebem, para esses usuários, a recusa descrita na tabela da seção 1.3.1.
Outras respostas:
| HTTP | Situação |
|---|---|
| 404 | O endereço chamado não corresponde a nenhuma empresa do CRTI ERP. Confira o endereço. |
| 403 | O acesso da empresa está bloqueado administrativamente. A resposta é uma página HTML, não JSON. |
1.3.3. 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.4. 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.
A renovação não pede o código da autenticação em dois fatores: ela mantém o que foi verificado no login. Se o login foi feito sem o código e o usuário passou a ter o 2FA exigido (cadastrou o aplicativo, ou a empresa passou a exigir), a renovação é recusada com HTTP 401 e motivoSegundoFator igual a SESSAO_SEM_CODIGO, e o usuário precisa entrar de novo, com o código.
A renovação também é recusada (HTTP 401) quando a credencial do usuário muda: troca de senha, troca do aplicativo autenticador ou remoção da autenticação em dois fatores pelo administrador. As sessões abertas antes deixam de valer, e o aplicativo deve pedir um novo login.
Toda recusa da renovação responde HTTP 401, e a resposta é sempre fazer o login de novo: refresh token vencido, inválido ou já usado, usuário bloqueado, sessão encerrada. Cada refresh token vale uma vez só, inclusive quando o cliente perde a resposta e repete o pedido, ou quando dois pedidos com o mesmo refresh chegam ao mesmo tempo: só o primeiro renova. Quem faz várias chamadas em paralelo deve renovar o token num ponto só e repartir o resultado.
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 5 dias."
}
1.3.5. 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.6. 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. URL de Acesso
2.1. URL Base
https://[nomedocliente].crti.com.br
Substitua [nomedocliente] pelo identificador único da empresa. Exemplo: https://construtora-abc.crti.com.br.
2.2. Documentação Swagger/OpenAPI
Disponível no endpoint /api: https://[nomedocliente].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:
- Cada credencial (X-API-Key, OAuth 2.0 ou Login/Senha) está vinculada a um usuário específico.
- Esse usuário pertence a um ou mais Grupos de Acesso.
- Os Grupos de Acesso definem quais recursos e operações são permitidos.
- 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 |
| 406 Not Acceptable | O cabeçalho Accept enviado não inclui o formato que o endpoint produz (ver abaixo) |
| 429 Too Many Requests | Limite de requisições excedido (ver seção 6.1) |
| 500 Internal Server Error | Erro interno do servidor |
Consulte o Swagger para detalhes específicos de cada endpoint.
Cabeçalho Accept: quando a requisição não traz Accept, a API assume application/json. Os endpoints que devolvem JSON funcionam sem ele. Os que devolvem outro formato (imagem, PDF, planilha) podem responder 406, sem corpo, se o Accept não vier ou não incluir o formato: envie, por exemplo, Accept: image/jpeg, ou Accept: */*.
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.
4.4. Paginação das Listagens
Os endpoints de listagem (GET sem id no caminho) são paginados pelos parâmetros page e limit. O que segue vale para a maior parte deles; o Swagger mostra os parâmetros e os filtros de cada um.
| Parâmetro | Significado | Quando não é informado |
|---|---|---|
page |
Número da página, começando em 0 | Página 0 |
limit |
Quantidade de itens por página | 1.000 itens; 20 quando só o page é informado |
GET /api/v1/cadastros/fornecedores?page=0&limit=500
Resposta:
{
"data": [ { "id": 1 }, { "id": 2 } ],
"totalLength": 1840,
"page": 0,
"limit": 500,
"offset": 0
}
| Campo | Significado |
|---|---|
data |
Itens da página. |
totalLength |
Total de itens que atendem ao filtro, somando todas as páginas. |
page, limit |
A página e o tamanho de página usados na consulta. |
offset |
Posição do primeiro item da página (page × limit). |
- Confira o
totalLength. Uma listagem chamada semlimitdevolve no máximo 1.000 itens, sem erro e sem aviso. Se ototalLengthfor maior que a quantidade recebida, peça as páginas seguintes (page=1,page=2…) até completar. - O limite de requisições conta chamadas, não itens (seção 6.1). Uma página maior traz a mesma lista em menos requisições: prefira um
limitmaior a muitas páginas pequenas. limitigual a zero ou negativo responde400.
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
- 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.
- Rotação de credenciais: revogue imediatamente credenciais comprometidas; gere novas pela interface do ERP.
- 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)
A API limita o número de requisições para que uma integração não prejudique o uso do ERP pelos demais usuários. Os limites são por empresa e por usuário: todas as credenciais (X-Api-Key, OAuth 2.0 ou login e senha) de um mesmo usuário dividem a mesma cota. Integrações diferentes devem usar usuários dedicados diferentes (ver seção 1.1.1).
| Rota | Limite no expediente | Limite fora do expediente | Contado por |
|---|---|---|---|
Todo /api/v1, somado |
200 requisições por minuto, somando todos os endpoints | 1.000 por minuto | usuário (só requisições autenticadas) |
/api/v1/bi/** (APIs de BI) |
1 requisição a cada 30 segundos, somando todos os endpoints de BI | 1 requisição por segundo | usuário |
Demais endpoints de /api/v1 |
60 requisições por minuto e no máximo 1 por segundo, em cada endpoint | 300 por minuto e no máximo 5 por segundo, em cada endpoint | usuário (sem autenticação, endereço IP) |
/oauth2/token |
300 requisições a cada 5 minutos | igual | endereço IP |
Cada requisição precisa caber em duas cotas ao mesmo tempo: a da soma de /api/v1 e a do seu endpoint (ou a do grupo de BI).
- Em cada endpoint significa por método e rota:
GET /api/v1/cadastros/fornecedoreseGET /api/v1/cadastros/fornecedores/{id}têm cotas separadas, mas consultar o fornecedor 10 e o fornecedor 11 conta na mesma cota deGET /api/v1/cadastros/fornecedores/{id}. - Todo
/api/v1, somado: além da cota de cada endpoint, há uma cota para a soma de todos eles, BI incluído. Ao exceder essa cota, todas as requisições do usuário à API são recusadas por 5 minutos, em qualquer endpoint, com oRetry-Afterdo tempo que falta. Como a cota é do usuário, integrações que compartilham o mesmo usuário compartilham também o bloqueio. Integrações que extraem muitos dados (ETL, carga de data warehouse) devem rodar fora do expediente, quando a cota é de 1.000 por minuto. - Fora do expediente é das 19h às 5h de segunda a sexta, e de sábado às 13h até segunda às 5h, no horário de Brasília. Feriados seguem o horário de um dia comum. Extrações volumosas, em especial as de BI, devem ser agendadas nessa janela.
- APIs de BI são consultas pesadas: a cota de 30 segundos vale para o conjunto delas, qualquer que seja o endpoint chamado. Fora do expediente, o limite passa a 1 por segundo.
- Token OAuth 2.0: o token vale 12 horas. Guarde-o e reutilize até perto do vencimento, em vez de pedir um token novo a cada requisição.
- Endpoint com id no caminho custa uma requisição por id. Como a cota é do endpoint, e não de cada id, buscar 100 registros por
GET /api/v1/cadastros/fornecedores/{id}leva pelo menos 100 segundos no expediente, e duas dessas chamadas no mesmo segundo já recebem429, mesmo com ids diferentes. Quando precisar de muitos registros, use a listagem com filtros e umlimitmaior (seção 4.4) e guarde o resultado. - A autenticação em dois fatores não altera os limites. Eles valem para toda requisição feita com token, chave ou OAuth, com ou sem o
codigoSegundoFatorno login.
Resposta ao exceder o limite: HTTP 429 Too Many Requests, com o cabeçalho Retry-After informando, em segundos, quanto esperar antes de repetir:
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json;charset=UTF-8
{"error":"too_many_requests","error_description":"Limite de requisições excedido. Tente novamente em 30 segundos."}
Durante o bloqueio de 5 minutos a resposta é a mesma, com o Retry-After do tempo que falta para o bloqueio acabar (até 300 segundos).
Nas respostas dentro do limite, o cabeçalho X-Rate-Limit-Remaining informa o que resta na cota do endpoint (ou do grupo de BI); a cota da soma não aparece nele. O valor é o menor entre o saldo do minuto e o saldo do segundo. Como o teto no expediente é de 1 requisição por segundo, ele vale 0 logo depois de cada requisição aceita, e isso não significa que a cota do minuto acabou. Fora do expediente, varia de 0 a 4.
Recomendações para o cliente da API:
- Faça as chamadas em sequência, uma por vez, em vez de disparar várias em paralelo para o mesmo endpoint.
- Ao receber
429, aguarde o tempo doRetry-Afterantes de repetir. Não repita imediatamente nem em laço: as requisições recusadas também contam na cota da soma, e insistir leva ao bloqueio de 5 minutos. - Use os filtros e a paginação dos endpoints para trazer só o necessário, e mantenha em cache os dados que mudam pouco (cadastros, tabelas auxiliares).
- Mantenha pelo menos 1 segundo entre duas chamadas ao mesmo endpoint no expediente. Não use o
X-Rate-Limit-Remainingpara dosar o ritmo: ele reflete o saldo do segundo, não o do minuto. - Em extrações volumosas, controle o ritmo do lado da integração para ficar abaixo das cotas, em vez de esperar o
429: fora do expediente, por exemplo, no máximo 1.000 requisições por minuto no total e 5 por segundo em cada endpoint.
6.2. Timeout de Requisições
Tempo limite: 10 segundos. Configure timeout adequado no cliente (mínimo 10s) e implemente retry com backoff exponencial.
Repita automaticamente só as leituras (GET). A API não tem chave de idempotência: se a resposta de uma criação (POST) não chegar, o registro pode ter sido gravado, e repetir o pedido pode criá-lo duas vezes. Nesse caso, consulte antes se o registro existe.
6.3. Procedimento para Reporte de Falhas
- Notifique o atendimento da CRTI pelo portal.
- O atendimento encaminha ao setor de desenvolvimento quando necessário.
- 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.