Como funciona a API do Optifora
Esta página descreve o formato da API: como a identidade é comprovada, como as versões avançam, dentro de que limites uma requisição se mantém, qual é a cara de um erro e como os dados são trocados com o mundo externo.
O produto está em desenvolvimento e a superfície da API ainda está sendo concluída. Um documento de referência dos pontos de acesso será publicado à parte; esta página não traz endereço nem exemplo de chamada, apenas a mecânica.
Autenticação
Toda requisição pertence a uma pessoa ou a um aplicativo registrado. Uma requisição sem identidade que chegue a um ponto de acesso protegido volta como não autenticada.
- Token BearerO token de acesso viaja no cabeçalho de autorização da requisição. Ele é assinado e diz apenas a quem a requisição pertence.
- Vida curtaUm token de acesso expira depois de um período medido em minutos; a duração é uma configuração da instalação e assume trinta minutos por padrão.
- Renovação e rotaçãoUma sessão é estendida com um token de renovação, e cada extensão emite um novo par. Se um token de renovação já usado for apresentado uma segunda vez, todas as sessões daquela pessoa são revogadas.
- As permissões não ficam gravadas no tokenO token carrega apenas a identidade; o que uma pessoa pode ver é perguntado ao banco de dados em cada requisição. Uma permissão retirada, portanto, para de funcionar antes de o token em mãos expirar.
- Chave do integradorUm aplicativo registrado se conecta com a própria chave. O valor em texto claro é mostrado uma única vez, no momento da criação; o que fica armazenado é o resumo criptográfico dela e o prefixo não secreto que permite reconhecer a chave.
- O acesso é concedido pela organizaçãoPor mais difundido que um aplicativo seja, sem uma autorização registrada pela organização ele não enxerga uma única linha. A autorização tem data, escopo definido e pode ser revogada.
Versionamento
- A versão fica no caminhoOs pontos de acesso são publicados atrás de um prefixo de versão; a superfície de hoje é a versão um.
- Uma mudança incompatível abre um novo caminhoO contrato de um ponto de acesso existente não é quebrado no lugar. Uma mudança incompatível é publicada em um novo caminho de versão, enquanto o antigo continua funcionando.
- O documento declara a própria versãoA referência carrega o número da versão a partir da qual foi gerada; qual versão você está lendo é respondido pelo próprio documento.
Ambientes e limites
A referência declara dois ambientes: produção e desenvolvimento local. O endereço raiz é entregue ao integrador junto com a chave dele; não é publicado nesta página.
- Atividade e prontidão são medidas separadamenteUm ponto de acesso diz que o processo está no ar; o segundo envia uma consulta real ao banco de dados e confirma que ele está acessível. Só o segundo decide se o tráfego deve ser enviado.
- As origens de navegador ficam restritas a uma listaRequisições de origem cruzada são aceitas apenas a partir de origens declaradas com antecedência; enquanto a lista estiver vazia, uma requisição de navegador de origem cruzada é recusada.
- Limite do corpoO corpo de uma requisição não pode passar de cinco megabytes. Conjuntos grandes viajam como um trabalho de transferência em lote, com registro de status próprio, e não como uma única requisição.
- Os segredos não são escritos no logO log do servidor não guarda cabeçalho de autorização, nem cookie, nem senha, nem número de identificação nacional.
Limite de frequência
O limite é por endereço e por minuto. O padrão é de 120 requisições por minuto e é definido na instalação. O que resta é informado em cabeçalhos em todas as respostas.
| Cabeçalho da resposta | O que indica |
|---|---|
| x-ratelimit-limit | O total permitido dentro da janela. |
| x-ratelimit-remaining | O que resta nesta janela. |
| x-ratelimit-reset | Segundos até o limite ser renovado. |
| retry-after | Quantos segundos até uma nova tentativa. Presente apenas na resposta que recusou a requisição. |
Depois que o limite é ultrapassado, a requisição é recusada e a resposta diz, em segundos, quanto tempo esperar. A nova tentativa é feita depois desse tempo, e não imediatamente.
Formato dos erros
Todo erro volta no mesmo envelope: um campo de código curto para a máquina decidir o caminho e um campo de explicação para uma pessoa ler.
- erroO código curto sobre o qual o cliente decide.
- messageA explicação do que aconteceu.
| Situação | Campo de código | O que significa |
|---|---|---|
| 400 | Bad Request | A requisição não corresponde ao esquema. A explicação indica o campo que está faltando ou inválido. |
| 401 | unauthenticated | Não há identidade válida: nenhum token foi enviado, ele expirou ou não foi verificado. |
| 404 | Not Found | Não existe esse ponto de acesso, ou não existe esse registro. |
| 429 | Too Many Requests | O limite de frequência foi excedido; a resposta diz quanto tempo esperar. |
| 5xx | internal_error | Uma falha inesperada. O detalhe não é entregue ao cliente; é escrito no log do servidor. |
Paginação
Os pontos de acesso que devolvem listas recebem os mesmos dois parâmetros e devolvem os mesmos contadores, de modo que um cliente de paginação não é reescrito para cada ponto de acesso.
- limitQuantos registros uma página deve conter. No mínimo um, no máximo duzentos; cinquenta quando não definido.
- offsetQuantos registros pular. Começa em zero.
- totalQuantos registros correspondem aos filtros no total.
- countQuantos registros esta resposta realmente carrega.
A resposta também devolve o limite e o deslocamento que usou; o cliente lê a sua posição na resposta em vez de adivinhá-la.
Troca de dados e webhooks
O modo de troca é uma configuração, não um produto à parte: cada aplicativo registrado carrega no próprio cadastro o modo em que trabalha.
| Modo | O que significa |
|---|---|
| Unidirecional — para fora | O Optifora publica os dados; o outro lado os lê ou assina os eventos. |
| Unidirecional — para dentro | O outro lado envia os dados; o Optifora os valida e os grava. |
| Bidirecional | Os dois lados escrevem; a regra de conflito é definida com antecedência. |
| Aperto de mão | Cada transferência abre uma sessão: proposta, verificação, aprovação, transferência e recibo. O recibo fica com os dois lados. |
- Os eventos são enviados para foraUm webhook envia o evento para o endereço de retorno declarado pelo aplicativo registrado. Um evento que não pode ser entregue fica na fila e é repetido; nunca é descartado em silêncio.
- A mesma requisição não escreve duas vezesUma requisição de escrita carrega uma chave de idempotência. Uma segunda requisição com a mesma chave não cria um segundo registro.
- Toda chamada é medidaQuem chamou, quando, com que escopo e com que resultado — tudo fica registrado. O mesmo registro responde tanto à depuração quanto à pergunta sobre quem puxou estes dados.
- Nossos próprios aplicativos usam a mesma portaNão existe um segundo caminho privilegiado. A nossa própria integração é a prova da superfície que um desenvolvedor externo encontra.
O modelo de dados da camada de troca está pronto; os pontos de acesso dela ainda não foram publicados. Quando forem, esta seção terá links para as entradas correspondentes na referência.
Documentos de referência
A referência não é escrita à mão; ela é gerada a partir dos esquemas dos pontos de acesso. À medida que cada ponto de acesso entrega o seu esquema, o documento se preenche sozinho, de modo que documento e comportamento não podem se afastar.
- Hoje: em preparaçãoOs esquemas avançam módulo a módulo. Antes de o documento ser publicado, a requisição e a resposta de cada ponto de acesso estarão visíveis nele.
- Serão publicados dois formatosUm documento OpenAPI legível por máquina e uma página de referência gerada a partir desse mesmo documento e navegável no navegador.
- O acesso é escalonadoA visão geral é aberta a qualquer pessoa. A referência completa pode ficar atrás de um token de documentação entregue a um integrador registrado; chaves de produção e endereços de retorno não são assunto de documentação — pertencem ao cadastro do aplicativo.
- Padrão de endereçosDuas referências são publicadas e seus endereços são fixos: client-api.optifora.com/docs é aberto, admin-api.optifora.com/docs exige autorização e está fechado ao exterior. Nenhum dos dois está no ar hoje; os links serão acrescentados a esta seção quando estiverem.
Se o seu plano de integração já estiver claro, escreva para nós pela página de contato: você estará entre os primeiros a saber quando a superfície abrir.
Você tem um pedido específico?
Estas páginas explicam como o processo de suporte funciona. Se você tiver um pedido ou uma dúvida, escreva para nós pela página de contato.
Ir para a página de contato