Conceitos fundamentais
Este artigo abrange todos os conceitos fundamentais para o uso dos serviços da API REST Oobj. Leia-o com atenção, prepare seu sistema de acordo com as instruções e aproveite ao máximo os serviços disponibilizados.
Autenticação e segurança
A autenticação e autorização na API são gerenciadas por tokens, utilizando o padrão JWT (JSON Web Token). Acesse o artigo Autenticação para encontrar detalhes desse procedimento;
Todas as comunicações com a API devem ser feitas exclusivamente por meio de HTTPS (HyperText Transfer Protocol Secure). O HTTPS criptografa os dados em trânsito e oferece uma camada adicional de segurança, garantindo que suas informações permaneçam privadas e protegidas.
Rate Limit
O Rate Limit é uma medida que limita o número de solicitações que um cliente pode fazer à API, dentro de um determinado período de tempo. Isso garante que a infraestrutura não seja sobrecarregada e que todos os clientes tenham acesso equitativo aos serviços;
Caso exceda o limite de requisições, o endereço IP de origem da requisição será bloqueado temporariamente, e o usuário receberá a seguinte mensagem:
{"message": "Too Many Requests", "error": {"status_code": 429, "retry_after": 300}}
Quando atingir o limite de requisições, sua aplicação deve ser capaz de lidar com isso de maneira eficaz, para que o usuário não seja impactado. Utilize o campo retry_after para saber quanto tempo esperar antes de fazer uma nova requisição.
Recomendamos que desenvolvedores implementem lógica de espera e monitoramento para gerenciar as solicitações e respeitar os limites de taxa, para que não tenham problemas com a disponibilidade dos serviços da API.
Abaixo está a relação de módulos, métodos e endpoints com seus respectivos limites:
Autenticação
| Método | Endpoint | Limite em 5 min. |
|---|---|---|
| POST | /api/authenticate | 100 |
| GET | /api/me | 100 |
| GET | /api/refresh | 100 |
Emissão e recebimento de DFes
Eventos fiscais
| Método | Endpoint | Limite em 5 min. |
|---|---|---|
| GET | Todos | 300 |
| POST | Todos | 300 |
| PUT | Todos | 300 |
Relatórios
| Método | Endpoint | Limite em 5 min. |
|---|---|---|
| POST | Todos | 100 |
Regra geral
Qualquer outro endpoint entra nesta regra
| Método | Endpoint | Limite em 5 min. |
|---|---|---|
| Todos | Todos | 1800 |
Formato de troca de mensagens
O formato para troca de mensagens mais utilizado é o JSON, com exceção dos endpoints de emissão de DFes e Eventos Fiscais, que aceitam outros formatos de envio, de acordo com o layout de integração utilizado.
O tipo de conteúdo retornado pela API varia entre JSON, XML e CSV, dependendo do endpoint utilizado. A codificação dos caracteres é UTF-8.
Códigos de status HTTP
| Status | Mensagem | Descrição |
|---|---|---|
| 200 | OK | Requisição realizada com sucesso. |
| 201 | Created | Recurso criado com sucesso. |
| 401 | Unauthorized | Usuário não autorizado. |
| 403 | Forbidden | Acesso proibido. |
| 404 | Not Found | Recurso não encontrado. |
| 429 | Too Many Requests | Limite de requisições excedido. |
Boas práticas e dicas gerais
- Evite solicitar um novo token desnecessariamente. O token expira somente depois de 30 (trinta) minutos de inatividade. Você só precisa obter um novo token quando o atual tiver ultrapassado esse tempo. Caso contrario, atualize o token no endpoint
GET /refresh;
- Sempre que receber um erro 401 em algum endpoint, verifique se o token usado não está expirado por meio do endpoint
GET /me;
- Evitar looping é fundamental para a saúde do ambiente, cliente e servidor. Evite laços infinitos de ações para os mesmos registros. Coloque um limitador de envios e um bom monitoramento para não cair no rate limit e receber o erro 429;
- É recomendado implementar um sistema de cache para armazenar dados que mudam com pouca frequência. Isso pode ajudar a reduzir a carga no servidor e melhorar o desempenho da aplicação.
Próximos passos
Agora que você já está por dentro de todos os conceitos por trás da API e das boas práticas recomendadas, consulte o artigo Primeiros passos, para começar a integração com a API REST Oobj.
