# Conceitos

Conceitos essenciais para usar a API: créditos, operações, ambiente e fluxo geral.

## Entendendo o seu papel

Na API Dados Jah existem dois atores principais:
- **Sistema**: quem administra a plataforma, a software house, cria usuários e gerencia contas.
- **Usuário (cliente)**: o cliente final, quem emite notas, cobranças, recebe pagamentos e etc.

O token gerado na autenticação do sistema serve apenas para acessar as rotas do sistema e não será possível usar este mesmo token para emitir uma nota fiscal ou gerar uma cobrança de PIX.

Da mesma forma o token gerado na autenticação do usuário não servirá para usar nas rotas do sistema, apenas do usuário. 

O token utilizado na autenticação define se é um sistema ou usuário e qual é o cadastro dentro da API, desta forma não acontece de usar um token para emitir nota e acabar sendo salva como para outro usuário.

### Fluxo para cadastrar um usuário

1. Com as credenciais de sistema, acesse a rota /auth/system/login e gere o token;
2. Com o token gerado, acesse a rota /user e cadastre o usuário (neste cadastro é informado também as credenciais, ou seja, o email e senha do usuário);

### Fluxo para o usuário fazer qualquer requisição

1. Com as credenciais de usuário, acesse a rota /auth/user/login e gere o token;
2. Com o token gerado, acesse qualquer rota;

## Tipos de dados em Requisições

Os campos devem ser enviados como string (texto com aspas duplas), mesmo quando representam valores numéricos ou decimais. Isso é vital para evitar problemas de precisão e compatibilidade entre diferentes sistemas.

- **Números e Identificadores**:
Campos como CNPJ/CPF, números de notas fiscais, códigos de municípios (IBGE), séries e outros identificadores numéricos:

Exemplos: "12345678901", "1596.00".

- **Valores Monetários**:
Valores decimais (ponto flutuante) devem usar o ponto (.) como separador decimal, e não a vírgula (,). Não devem ter separador de milhar.

Correto: "10.50", "3.14", "0.75", "3785.96231"

Incorreto: "10,50", "3,14", "0,75", "3.785,96231"

- **Datas e Horas**:
Campos como dhEmi, dhRecbto, dhEvento devem ser enviados como strings no formato ISO 8601. 

Máscara: "AAAA-MM-DD'T'HH:mm:ss-ZZ:ZZ".

Exemplo: "2029-01-31T15:20:45-03:00".

- **Arquivos**:
Campos como certificado digital, imagens e pdf´s são enviados e recebidos em [base64](https://www.base64decode.org/).


### Exceções: Booleanos e Nulos

Os campos do tipo booleano deve ser enviados como **true** ou **false**, sem aspas duplas ("") ou aspas simples (''). Já os campos que precisam ser nulos, devem ser enviados como **null**.

Correto: true, false, null

Incorreto: "true", 'false', "NULL"

## Campos

A API segue o nome dos campos conforme documentação técnica referente ao serviço como é o caso da API DFe (ex.: xJust, xCorrecao, dhEvento, etc) ou usando o inglês para descrever o campo (ex.: createdAt, resSituationReason, situation, etc). Consulte documentação técnica do serviço como é dos documentos fiscais ou documentação interna da API para saber o que é cada campo.

Alguns campos podem ser utilizados com o mesmo nome e sentido entre diversas API, abaixo uma lista destes campos:

### situation:

Embora não seja um objeto ou código retornado como padrão nas requisições, é possível que em alguns endpoints seja retornado o campo *situation* (situação). Este campo indica o status interno da requisição na API.
**Valores**:
- **Received**: A requisição foi recebida pela API e está aguardando processamento inicial.
- **InProcessing**: A requisição está sendo processada pela API.
- **Processed**: A requisição foi processada com sucesso pela API.
- **Error**: Ocorreu erro durante o processamento. Verifique o campo *message*.

### idExternal:

Id Externo, é o ID da sua aplicação em relação a um recurso da API. 
Exemplo: As notas fiscais com o id "2sBXiko-1d1d2d1" e "121sds1-sdf1s2fs" tem o idExternal com o valor "12345".

O campo idExternal não é único ou obrigatório, logo é possível enviar uma requisição sem ele, a API não vai gerar um id para ele, manterá conforme enviado ou última alteração.

É possível realizar consultas a recursos na API usando o idExternal e com isto retornar todos os recursos que tem este código vinculado.



## Estrutura Geral das Respostas da API

Todas as respostas da API seguem uma estrutura padrão, especialmente em relação ao status e aos dados retornados.

### statusCode:
**Descrição**: O código de status HTTP da resposta.

**Valores**:
- **200 OK**: Requisição processada com sucesso; dados no campo data.
- **201 Created**: Requisição processada com sucesso e um novo recurso foi criado (ex: usuário, token, cadastro).
- **400 Bad Request**: Requisição inválida (erros de validação). O campo message detalhará os erros.
- **401 Unauthorized**: Autenticação falhou (token ausente, inválido ou expirado).
- **403 Forbidden**: Usuário/sistema autenticado, mas sem permissão para a ação/recurso.
- **409 Conflict**: Conflito de dados (ex: recurso com dados únicos já existente).
- **500 Internal Server Error**: Error interno do sistema. Entre em contato com o suporte.

### data:

**Descrição**: O objeto que contém os dados da resposta da API.

**Observação**: A estrutura e o conteúdo variam conforme o endpoint.

### message (em caso de erro):

**Descrição**: Um array de strings com mensagens detalhadas sobre o erro.

**Observação**: Em erros como 400 ou 409, lista todos os problemas encontrados na requisição.

### error (em caso de erro):

**Descrição**: Uma descrição geral do tipo de erro HTTP.

**Observação**: Complementa o statusCode (ex: "Unauthorized", "Bad Request").



