Introdução

A OrçaFascio disponibiliza uma API REST para integração com sistemas, aplicações e serviços externos. Por meio dessa interface, as soluções integradas podem consultar informações e executar operações relacionadas às empresas que utilizam a plataforma OrçaFascio.

A comunicação com a API é realizada exclusivamente por meio do protocolo seguro HTTPS. Os dados enviados e recebidos são estruturados no formato JSON.

Endereços base

As versões da API são organizadas por meio de caminhos específicos adicionados ao endereço principal do serviço.

Cada versão possui um endereço base independente:

API v1: https://api.orcafascio.com/api/v1

API v2: https://api.orcafascio.com/api/public/v2/

Os endpoints apresentados nesta documentação devem ser acrescentados ao endereço base correspondente à versão utilizada.

Versionamento

O versionamento permite que novos recursos, melhorias e alterações de comportamento sejam disponibilizados sem comprometer as integrações existentes.

A partir da versão 2, as evoluções da API poderão ser implementadas de forma independente da versão anterior, preservando a compatibilidade e oferecendo um processo de migração mais seguro para os sistemas integrados.

Padrões da API v2

Media types

As respostas da API v2 utilizam o seguinte media type:

O corpo das requisições pode ser enviado no formato JSON, utilizando:

Quando necessário, o cliente também pode informar os formatos de resposta aceitos:

Estrutura dos documentos

Recurso individual

As respostas que representam um único recurso seguem a estrutura abaixo:

Os principais campos são:

type: identifica o tipo do recurso;

id: identifica unicamente o recurso;

attributes: contém os atributos do recurso;

relationships: contém os relacionamentos com outros recursos, quando disponíveis.

Coleção de recursos

As respostas que representam uma coleção utilizam um array no campo data:

O objeto meta apresenta informações complementares, como a quantidade total de registros encontrados.

O objeto links disponibiliza os endereços relacionados à navegação entre as páginas da coleção:

first: primeira página;

prev: página anterior;

next: próxima página;

last: última página.

Estrutura de erros

Quando uma requisição não puder ser processada, a API retornará um array de erros:

Cada erro poderá apresentar os seguintes campos:

status: código HTTP relacionado ao erro;

code: código interno e identificável do erro;

title: descrição resumida;

detail: descrição detalhada, quando disponível;

source: origem do erro na requisição, quando aplicável.

Autenticação

Com exceção do endpoint de autenticação, todas as rotas protegidas exigem o envio de um token de acesso no cabeçalho Authorization.

O token deve ser obtido por meio do endpoint:

Após a autenticação, o token recebido deverá ser informado em todas as requisições realizadas aos endpoints protegidos da API.

Idioma e internacionalização

A API v2 oferece suporte aos seguintes idiomas:

Português do Brasil: pt-BR;

Inglês: en;

Espanhol: es.

O idioma da resposta pode ser definido por meio do cabeçalho Accept-Language:

Também é possível sobrescrever o idioma utilizando o parâmetro idioma na URL:

Quando informado, o parâmetro idioma possui prioridade sobre o cabeçalho Accept-Language.

A resposta apresenta o idioma utilizado no cabeçalho:

Os nomes dos campos, atributos e caminhos da API são padronizados em inglês e não são alterados de acordo com o idioma selecionado.

Valores enumerados são apresentados com um código canônico e um rótulo traduzido:

O campo codigo deve ser utilizado pelas integrações para validações e regras de negócio, enquanto o campo rotulo deve ser utilizado apenas para apresentação ao usuário.

Paginação

Os endpoints que retornam coleções utilizam paginação baseada nos parâmetros page[number] e page[size].

Parâmetros disponíveis:

page[number]: número da página solicitada;

page[size]: quantidade de registros por página.

O tamanho padrão da página é de 30 registros, e o limite máximo permitido é de 100 registros por página.

Filtros

Os filtros devem ser informados utilizando o padrão filter[campo]:

É possível combinar múltiplos filtros em uma mesma requisição:

Os campos disponíveis para filtragem podem variar de acordo com o endpoint.

Ordenação

A ordenação dos resultados é realizada por meio do parâmetro sort.

Para ordenar em ordem crescente:

Para ordenar em ordem decrescente, deve-se adicionar o caractere - antes do nome do campo:

Quando suportado pelo endpoint, múltiplos campos de ordenação podem ser enviados separados por vírgula:

Endereços base#

Versionamento#

Padrões da API v2#

Media types#

Estrutura dos documentos#

Recurso individual#

Coleção de recursos#

Estrutura de erros#

Autenticação#

Idioma e internacionalização#

Paginação#

Filtros#

Ordenação#