API de Extração de Dados

Introdução

Sobre a API de Extração

A API de Extração de Dados disponibiliza, de forma padronizada e segura, os dados que a sua filial (tenant) gera na plataforma phusion. Ela foi desenhada para integrações sistema a sistema: um processo do seu lado consulta a API periodicamente, grava os registros recebidos na sua base e confirma o recebimento.

É uma API de consumo de dados: as únicas chamadas de escrita são as de controle da própria integração — confirmar um pacote, solicitar ou cancelar um reprocessamento.

Para quem é esta documentação

Para a equipe técnica do parceiro responsável por construir e operar a integração: desenvolvedores, engenheiros de dados e arquitetos. Os exemplos usam cURL e pseudocódigo, e podem ser reproduzidos em qualquer linguagem que tenha um cliente HTTP.

O que você consegue fazer

Como a integração funciona, em resumo

Os dados são organizados em recursos (por exemplo, orcamentos-vendas-produto), liberados individualmente conforme o seu contrato. Cada recurso tem a sua própria fila de pacotes. O ciclo é sempre o mesmo: pedir o próximo pacote, gravar os itens, confirmar a sequência. Enquanto não houver confirmação, o mesmo pacote continua sendo devolvido — nenhum dado é pulado, e por isso a gravação do seu lado precisa ser feita por upsert.

O que você precisa ter

Jornada de integração

1. 1 · AcessoReceba as credenciais e os códigos dos recursos liberados (Dados de acesso) e mapeie os campos de cada recurso (Modelo de dados).
2. 2 · AutenticaçãoObtenha o token em /api/auth e envie-o, com o tenantId, em todas as chamadas (Autenticação).
3. 3 · Carga inicialSolicite o reprocessamento do histórico em blocos de até 90 dias e consuma as partes até o fim (Reprocessamento).
4. 4 · Regime contínuoColoque o laço incremental em operação, consultando cada recurso periodicamente (Laço de consumo).
5. 5 · HomologaçãoValide os cenários do Checklist de homologação no ambiente STG.
6. 6 · ProduçãoTroque URLs e credenciais pelas de produção, compartilhadas pela nossa equipe em um segundo momento.

Introdução

Visão geral

Os dados da sua filial (tenant) são disponibilizados em pacotes sequenciais, no formato JSON.

Você pergunta à API se há algo a consumir. Havendo, o próprio pacote vem na resposta, com os registros no campo dados. Depois de gravar esses registros, você confirma o pacote, e só então a plataforma libera o próximo.

1. Cliente → APIGET próximo pacote.
2. API → Cliente200 com o pacote: { sequencia, quantidadeItens, dados: [...] } — ou 204 se não há o que consumir.
3. Cliente → APIPOST confirmação { sequencia }.
4. API → Cliente204 — libera o próximo pacote.

Três características definem o modelo

Dois fluxos

Os dois fluxos têm o mesmo formato de pacote e a mesma mecânica de confirmação:

Introdução

Conceitos

Comece por aqui

Dados de acesso

Quando a integração é ativada, você recebe um e-mail automático da Fagron Tech ("Ativação de Integração concluída") com:

Ambientes e URLs

STG

Produção

Comece por aqui

Autenticação

Troque o IntegradorId e a senha recebidos por e-mail por um token de acesso (JWT) e envie-o como Bearer no cabeçalho Authorization das demais chamadas.

Corpo (JSON)

Exemplo cURL

curl --location 'https://fate-mobypharma-integradores-api-stg.fagrontechnologies.com.br/api/auth' \
--header 'Content-Type: application/json' \
--data '{
  "usuario": "{{INTEGRADOR_ID}}",
  "senha": "{{SENHA}}"
}'

Respostas

{
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIs...",
    "tokenType": "Bearer",
    "expiresIn": 108000,
    "scope": "fate_integradores"
  },
  "success": true,
  "errors": []
}

{
  "success": false,
  "errors": [
    "Usuário ou senha inválidos"
  ]
}

Usando o token

Authorization: Bearer {{ACCESS_TOKEN}}

Comece por aqui

Cabeçalhos obrigatórios

Toda chamada à API de extração exige:

API · Fluxo incremental

Obter o próximo pacote

Caminhos relativos à URL base. {recurso} é o código do recurso (ex.: orcamentos-vendas-produto).

GET /api/extracao/{recurso}/alteracoes
Authorization: Bearer {accessToken}
tenantId: {guid}

Respostas

Exemplo de resposta

Exemplo de resposta 200 para o recurso orcamentos-vendas-produto (valores fictícios; um único item mostrado e parte dos campos omitida — a lista completa está em Modelo de dados):

{
  "sequencia": 1,
  "quantidadeItens": 4850,
  "dados": [
    {
      "tipoItem": 1,
      "itemId": 1000001,
      "pedidoId": 500001,
      "codigo": 12345,
      "produto": "TALCO",
      "grupo": "Raw material",
      "setor": "SOLIDOS",
      "formaFarmaceutica": "Creme",
      "serie": "0",
      "pedido": 13,
      "dataOrcamento": "2022-10-06T19:19:00",
      "dataAprovacao": "2022-10-06T19:19:44",
      "filialId": 1001,
      "filial": "1 - MATRIZ",
      "quantidade": 0.00100,
      "unidade": "G",
      "cliente": "NOME DO CLIENTE",
      "prescritor": "Nome do Prescritor",
      "aprovador": "Nome do Aprovador",
      "orcamentista": "Nome do Orçamentista",
      "pedidoItemStatusId": 3,
      "statusFinanceiroId": 2,
      "origemAcrescimoDesconto": null,
      "convenio": null,
      "cortesia": false
    }
  ]
}

Configuração do cliente HTTP

O pacote é entregue por meio de um redirecionamento HTTP (302) para um endereço temporário e assinado da plataforma. Com o cliente configurado para seguir redirecionamentos, isso é transparente: a resposta final que a sua aplicação recebe é o 200 com o pacote.

• Habilite o seguimento de redirecionamentos. É o padrão na maioria das bibliotecas HTTP; em curl, use a opção -L.
• Não armazene nem reutilize o endereço do redirecionamento: ele expira em até 30 minutos. Em caso de falha ao receber o pacote, repita o GET.

API · Fluxo incremental

Confirmar o consumo

POST /api/extracao/{recurso}/alteracoes/confirmacoes
Authorization: Bearer {accessToken}
tenantId: {guid}
Content-Type: application/json

{
  "sequencia": 42
}

O valor de sequencia é o que veio no pacote recebido (ver Formato do pacote).

Respostas

Confirmação repetida. Se você reenviar a confirmação de uma sequência já aceita (por exemplo, porque a resposta do primeiro POST se perdeu), a resposta é 204 enquanto não houver outro pacote pendente. Se o pacote seguinte já estiver disponível, a resposta é 409. Em ambos os casos a confirmação original continua válida: diante de um 409, refaça o GET — se ele trouxer uma sequencia maior que a que você confirmou, a confirmação anterior já havia sido aceita e basta seguir com o novo pacote.

API · Fluxo incremental

Formato do pacote

Vale para os dois fluxos. Documento JSON UTF-8 com BOM (application/json, sem compactação), com envelope fixo:

{
  "sequencia": 42,
  "quantidadeItens": 100,
  "dados": [ /* ... um objeto por item ... */ ]
}

Regras do payload

• O arquivo começa com o BOM do UTF-8 (bytes EF BB BF). Configure o parser para aceitá-lo (ex.: em Python, abrir o arquivo com encoding="utf-8-sig").
• Nomes de campos em camelCase, exatamente como em Modelo de dados (ex.: itemId).
• Campos nulos são entregues explicitamente como null — a chave está presente.
• Datas e horas seguem o formato ISO 8601 sem indicação de fuso (2019-06-17T16:45:00), como gravadas na origem (UTC). A conversão para o fuso de exibição é do consumidor.
• Valores monetários e quantidades são números decimais.
• Não há marcador artificial de remoção. Itens cancelados, deletados ou em cortesia são entregues normalmente, sinalizados pelos próprios campos de negócio (ex.: deletado, cortesia, campos de status). A exclusão é comunicada pelo campo, nunca pela ausência da linha.

Integração incremental

Laço de consumo

repetir:
    resposta = GET /api/extracao/{recurso}/alteracoes

    se resposta.status == 204:
        aguardar o intervalo de consulta  →  voltar ao início

    pacote = corpo da resposta (JSON)

    para cada item em pacote.dados:
        upsert(item)          # ver Deduplicação e idempotência

    commit da persistência    # só depois disso:

    POST /api/extracao/{recurso}/alteracoes/confirmacoes { sequencia: pacote.sequencia }

    voltar ao início imediatamente   # pode haver mais pacotes na fila

O upsert deve seguir as regras de deduplicação e idempotência.

Integração incremental

Exemplo com cURL

O exemplo usa variáveis de ambiente ($API_BASE, $INTEGRADOR_ID, $SENHA, $TENANT_ID) com os dados fornecidos pela Fagron Tech, e o jq para ler o JSON das respostas.

# 1. Obter o token com o IntegradorId e a senha do e-mail de ativação
TOKEN=$(curl -s -X POST "$API_BASE/api/auth" \
  -H "Content-Type: application/json" \
  -d "{\"usuario\": \"$INTEGRADOR_ID\", \"senha\": \"$SENHA\"}" | jq -r .data.accessToken)

# 2. Pedir o próximo pacote (-L segue o redirecionamento interno; -w mostra o
#    status final: 200 com o pacote, ou 204 se não há nada novo)
curl -sL -o pacote.json -w '%{http_code}\n' \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenantId: $TENANT_ID" \
  "$API_BASE/api/extracao/orcamentos-vendas-produto/alteracoes"

# 3. Confirmar, usando a sequência que veio no pacote
SEQ=$(jq -r .sequencia pacote.json)
curl -s -X POST "$API_BASE/api/extracao/orcamentos-vendas-produto/alteracoes/confirmacoes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenantId: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d "{\"sequencia\": $SEQ}"

Integração incremental

Frequência e ritmo

• Sugestão inicial: consultar a cada 5 minutos por recurso.
• Depois de confirmar um pacote, consulte de novo imediatamente: pode haver fila acumulada. Só volte ao intervalo normal quando receber 204.
• Consuma um pacote por vez, em ordem de sequência. Não paralelize o consumo do mesmo recurso. Recursos diferentes são filas independentes e podem ser consumidos em paralelo.
• Consuma com regularidade. Longos períodos sem consumo fazem a fila acumular e podem atrasar a disponibilização de novos pacotes.

API · Reprocessamento

Reprocessamento por período

Fluxo assíncrono, filtrado por data de negócio, usado para a carga inicial do recurso e para recompor um intervalo já passado.

• É um retrato do período (versão atual de cada item), não um delta.
• O download segue o mesmo modelo do incremental: 302 para um link temporário, arquivo no formato do pacote e confirmação explícita da sequência.
• O resultado é entregue em partes sequenciais, e é a confirmação de uma parte que libera a geração da parte seguinte. Sem confirmar, o reprocessamento não avança.
• Um reprocessamento ativo por vez, por recurso. Para recompor janelas longas, solicite blocos sucessivos.
• Janela máxima de 90 dias por solicitação, com as duas datas inclusivas.

API · Reprocessamento

Solicitar reprocessamento

POST /api/extracao/{recurso}/reprocessos
Authorization: Bearer {accessToken}
tenantId: {guid}
Idempotency-Key: {chave-unica}
Content-Type: application/json

{
  "dataInicio": "2026-01-01",
  "dataFim": "2026-03-31"
}

Regras

• As duas datas são obrigatórias e inclusivas, e devem ser enviadas como datas puras, no formato AAAA-MM-DD, sem hora e sem fuso. Um valor com offset é recusado com 400, para que a janela nunca seja deslocada em silêncio.
• dataInicio não pode ser maior que dataFim.
• O cabeçalho Idempotency-Key é obrigatório (sem ele, a resposta é 400). Gere um valor único por solicitação (ex.: um GUID). Reenviar a mesma chave com o mesmo corpo, dentro da janela de retenção, devolve a resposta original sem criar outro reprocessamento — útil quando a resposta se perde por timeout. Reutilizar a chave com um corpo diferente é recusado com 409.

Respostas

{
  "chaveProcessamento": "8f1d1b64-6b25-4a7a-9a5a-3c2e1b0a77d1",
  "status": "aguardando"
}

API · Reprocessamento

Consultar o status

GET /api/extracao/{recurso}/reprocessos/{chaveProcessamento}
Authorization: Bearer {accessToken}
tenantId: {guid}

{
  "status": "processando",
  "dataInicio": "2026-01-01T00:00:00",
  "dataFim": "2026-03-31T00:00:00",
  "quantidadeItens": 24000,
  "partes": [
    { "sequencia": 1, "quantidadeItens": 12000, "consumidoEm": "2026-04-02T13:20:41.807299Z" },
    { "sequencia": 2, "quantidadeItens": 12000 }
  ]
}

Significado de cada status

API · Reprocessamento

Obter a próxima parte

GET /api/extracao/{recurso}/reprocessos/{chaveProcessamento}/proximo-arquivo
Authorization: Bearer {accessToken}
tenantId: {guid}

Respostas

API · Reprocessamento

Confirmar uma parte

POST /api/extracao/{recurso}/reprocessos/{chaveProcessamento}/confirmacoes
Authorization: Bearer {accessToken}
tenantId: {guid}
Content-Type: application/json

{
  "sequencia": 2
}

Respostas

API · Reprocessamento

Cancelar

POST /api/extracao/{recurso}/reprocessos/{chaveProcessamento}/cancelamento
Authorization: Bearer {accessToken}
tenantId: {guid}

Respostas

Cancelar libera o recurso para uma nova solicitação. As partes já baixadas e persistidas continuam válidas; o que se perde é a continuação do período.

API · Reprocessamento

Laço de consumo do reprocessamento

resposta = POST /api/extracao/{recurso}/reprocessos { dataInicio, dataFim }
chave    = resposta.chaveProcessamento

repetir:
    parte = GET /api/extracao/{recurso}/reprocessos/{chave}/proximo-arquivo

    se parte.status == 302:                      # seguindo o redirecionamento
        arquivo = corpo do download (JSON)
        para cada item em arquivo.dados: upsert(item)
        commit da persistência
        POST /api/extracao/{recurso}/reprocessos/{chave}/confirmacoes { sequencia: arquivo.sequencia }
        voltar ao início imediatamente           # a confirmação libera a parte seguinte

    se parte.status == 202:                      # parte seguinte ainda em geração
        aguardar Retry-After segundos  →  voltar ao início

    se parte.status == 204:                      # concluido, sem mais partes
        fim

    se parte.status == 409:                      # falhou, cancelado ou arquivo indisponível
        estado = GET /api/extracao/{recurso}/reprocessos/{chave}
        tratar conforme estado.status  →  fim

Modelo de dados

Recursos disponíveis

Cada recurso é liberado individualmente para o seu contrato. O código do recurso é o valor de {recurso} nos caminhos da API, e o conjunto de campos de dados é o mesmo nos fluxos incremental e de reprocessamento.

Como ler as tabelas de campos

• Os campos estão na ordem em que aparecem em cada item de dados.
• Todos os campos podem vir null; a chave sempre está presente.
• datetime segue o formato ISO 8601 sem fuso (2019-06-17T16:45:00), conforme Formato do pacote.
• Campos de domínio vêm em par: o identificador numérico (ex.: statusFinanceiroId) e a sua descrição textual em português (ex.: statusFinanceiro). Para regras de negócio, use o identificador; os valores possíveis estão em Valores de domínio.

Modelo de dados

Itens de orçamentos e pedidos

Itens de orçamentos e pedidos, com valores, envolvidos, status e datas.

Modelo de dados

Gestão de pedidos

Itens de pedidos com canal de atendimento, valores, convênio, envolvidos e status do pedido, do item e financeiro.

Modelo de dados

Despesas e receitas

Lançamentos financeiros de despesas e receitas, com datas, valores, plano de contas, dados bancários e status de pagamento.

Modelo de dados

Gestão de entregas

Entregas com romaneio, tipo, status, valores, região, entregador, cliente, destinatário e endereço de destino.

Modelo de dados

Orçamentos e vendas por produto

Itens de orçamentos e vendas por produto, com grupo, setor, envolvidos, status, preços e dados do lote.

Modelo de dados

Valores de domínio

Valores possíveis dos campos de domínio, com a descrição textual entregue no campo correspondente.

PedidoItemStatus

Status do item do pedido.

StatusFinanceiroPedido

Status financeiro do pedido.

OrigemAcrescimoDesconto

Origem do acréscimo ou desconto.

StatusPedido

Status do pedido.

TipoEntrega

Tipo da entrega.

StatusEntrega

Status da entrega.

TipoDestinatario

Tipo do destinatário da entrega.

StatusPagamentoLancamento

Status de pagamento do lançamento.

TipoPagamento

Forma de pagamento.

TipoReceita

Tipo da receita.

Referência

Deduplicação e idempotência (obrigatório)

Como a entrega é at-least-once, o mesmo item pode chegar mais de uma vez — no reprocessamento de um pacote não confirmado, em pacotes distintos quando o registro sofre novas alterações, ou na sobreposição entre uma carga por período e o fluxo incremental.

• Faça upsert pela chave natural do item do recurso (informada pela Fagron Tech).
• Considere sempre a última versão recebida como a verdadeira.
• Nunca trate a carga como insert-only.
• Persista o pacote inteiro antes de confirmar. Se o seu processo cair entre o recebimento e a confirmação, basta repetir o GET: o mesmo pacote volta.

Referência

Erros e respostas HTTP

Referência

Checklist de homologação

• Credenciais (IntegradorId, senha e tenantId) recebidas por e-mail e token obtido com sucesso em /api/auth
• Códigos dos recursos liberados confirmados
• Campos de cada recurso mapeados conforme o Modelo de dados
• Cliente HTTP configurado para seguir redirecionamentos sem repassar Authorization/tenantId
• Laço incremental implementado: GET → persistência do pacote → confirmação
• 204 tratado como "sem novidades", e não como erro
• Upsert idempotente pela chave natural validado com o mesmo pacote entregue duas vezes
• Reentrada após queda entre o recebimento do pacote e a confirmação testada
• Tratamento de 401 (renovação de token) e 409 testado
• Idempotency-Key único enviado em cada solicitação de reprocessamento
• Consulta imediata após confirmação (drenagem de fila acumulada) implementada
• Carga inicial executada por reprocessamento, com drenagem das partes até o 204 (tratando 202 + Retry-After)
• Comportamento de concluido com parte ainda não confirmada validado
• Período maior que 90 dias fatiado em solicitações sucessivas
• Monitoramento do atraso do consumo (horário da última confirmação) configurado

Referência

Suporte

Dúvidas sobre contrato, campos, liberação de recursos ou incidentes de integração devem ser direcionadas ao canal de suporte acordado com a Fagron Tech, informando:

• o recurso;
• a sequência (ou a chaveProcessamento) envolvida;
• o tenantId;
• o horário aproximado da ocorrência;
• quando disponível, o valor do cabeçalho fate-correlationid devolvido na resposta da chamada.