Saltar para o conteúdo

Primeiros pedidos

A forma da API, os grupos de endpoints por área, e o que esperar de uma resposta de erro. O suficiente para o primeiro script.

Avançado6 min de leitura

A forma

  • Base: https://api.fortfox.pt
  • Versão: /v1
  • Corpo: JSON, com Content-Type: application/json
  • Autenticação: Authorization: Bearer … — ver Autenticação e tokens

O primeiro pedido

curl -H "Authorization: Bearer ffpat_..." \
     https://api.fortfox.pt/v1/sites

Devolve os sites a que a credencial tem acesso. Se um token estiver limitado a sites, a lista já vem filtrada — a restrição não é uma verificação no fim, é o que a leitura faz.

Os dois grupos

/v1/me/… — a minha conta

O que é da conta ou da pessoa, e não de um site:

ÁreaPara que serve
/v1/me/api-tokensgerir tokens (só com sessão, não com token)
/v1/me/webhookssubscrições de webhooks e as entregas recentes
/v1/me/ticketspedidos de suporte
/v1/me/notificationsa inbox de acontecimentos

/v1/sites/… — um site

Tudo o que diz respeito a um site em concreto, com o id no caminho:

CaminhoÁrea
/v1/sites/{id}o site: ler, actualizar, apagar
/v1/sites/{id}/originsorigens e verificações de saúde
/v1/sites/{id}/domainsdomínios próprios e verificação
/v1/sites/{id}/cache-rulesregras de cache
/v1/sites/{id}/waf/…configuração da firewall e regras
/v1/sites/{id}/rate-limitlimite de pedidos
/v1/sites/{id}/analytics/…tráfego, cache, ameaças, top IPs
/v1/sites/{id}/dns/…zona DNS, quando alojada por nós

Nem todos exigem o mesmo: as leituras precisam de uma permissão de ver, as escritas de uma de gerir. A especificação diz-o por endpoint.

Erros

Um erro traz um código estável e, quando ajuda, uma mensagem:

{
  "error_code": "VALIDATION_ERROR",
  "message": "o assunto precisa de pelo menos 3 caracteres"
}

Programa contra o error_code, e não contra a mensagem. O código é contrato; a mensagem é texto para pessoas e pode mudar.

EstadoO que costuma querer dizer
400o corpo do pedido está mal — a mensagem diz qual o campo
401credencial ausente, expirada ou revogada
403a credencial é válida e não chega para isto
404não existe, ou não é teu — não distinguimos os dois
409conflito: já existe algo igual
422o pedido é coerente e a regra de negócio recusa
429demasiados pedidos — ver Limites de pedidos
5xxnosso. Vale a pena tentar outra vez com recuo.

O 404 que também é um 403

Um recurso de outra conta responde 404, e não 403. É deliberado: a diferença entre «não existe» e «existe e não é teu» é informação, e quem anda a sondar ids aprende com ela.

A especificação completa

A plataforma publica o OpenAPI, e é a fonte a usar para gerar clientes ou validar contratos. A documentação interactiva vive no endpoint de documentação da API.

Se um endpoint aqui e a especificação discordarem, a especificação está mais próxima do código — este guia é uma introdução, não o contrato.

Escrever um script que não se parte

  • Guarda o error_code, não a mensagem.
  • Trata o 429 com recuo, e respeita o que a resposta indicar.
  • Não presumas ordem numa lista sem parâmetro de ordenação.
  • Não presumas campos. Acrescentamos campos às respostas sem aviso; isso não é uma alteração de contrato. Retirar seria.
  • Um id é opaco. Não deduzas nada da forma dele.

← Toda a documentação