Login

GET /flow/restful/application/login?validity=900

Autentica uma conta Flow habilitada para email e senha. Uma conta criada apenas por login social pode precisar de configuração própria para utilizar a API.

Resposta de sucesso — HTTP 200

{
  "status": {
    "code": 100,
    "name": "SUCCESS",
    "detail": "Operação realizada com sucesso"
  },
  "access_token": "<token>",
  "validity": 900
}

Erros de aplicação

Nas chamadas protegidas, INVALID_ACCESS_TOKEN (700) indica token inválido e EXPIRED_ACCESS_TOKEN (701) indica token expirado, conforme o contrato. Corrigir a autenticação sem recriar operações já aceitas.

ModelsList

GET /flow/restful/application/models

Lista os modelos visuais da conta. Consultar os modelos existentes antes de cadastrar outro.

Resposta de sucesso — HTTP 200

{
  "status": {
    "code": 100,
    "name": "SUCCESS",
    "detail": "Operação realizada com sucesso"
  },
  "signature_model_list": [
    {
      "id": "123",
      "SignatureModel": {
        "name": "Modelo do integrador",
        "model_type": "TEXT_ONLY",
        "height": 75,
        "width": 150,
        "custom_text": "Assinado digitalmente por:",
        "custom_text_name": true,
        "custom_text_cpf": true,
        "custom_text_date": true,
        "image_position": "LEFT",
        "text_font": "HELVETICA",
        "text_size": 6,
        "text_padding": 5,
        "text_alignment": "LEFT"
      }
    }
  ]
}

Falhas de autenticação seguem o tratamento geral. Os campos de cada SignatureModel são descritos em RegisterModel.

RegisterModel

POST /flow/restful/application/register-signature-model

Cadastra uma configuração de apresentação da assinatura no PDF. Tipos disponíveis: IMAGE_ONLY (imagem), TEXT_ONLY (texto) e IMAGE_WITH_TEXT (imagem e texto). Conferir a configuração e a apresentação final no fluxo escolhido.

Corpo JSON

Omitir campos opcionais para utilizar os padrões documentados; enviar string vazia não equivale a omitir. Os nomes corretos são text_size, text_alignment e BOTTOM.

{
  "name": "Modelo do integrador",
  "model_type": "TEXT_ONLY",
  "width": 150,
  "height": 75,
  "text_size": 6,
  "text_alignment": "LEFT"
}

Resposta de sucesso — HTTP 201

{
  "status": {
    "code": 100,
    "name": "SUCCESS",
    "detail": "Operação realizada com sucesso"
  },
  "signature_model": {
    "id": "123",
    "SignatureModel": {
      "name": "Modelo do integrador",
      "model_type": "TEXT_ONLY",
      "height": 75,
      "width": 150,
      "custom_text": "Assinado digitalmente por:",
      "custom_text_name": true,
      "custom_text_cpf": true,
      "custom_text_date": true,
      "image_position": "LEFT",
      "text_font": "HELVETICA",
      "text_size": 6,
      "text_padding": 5,
      "text_alignment": "LEFT"
    }
  }
}

Persistir o ID e reutilizar o modelo. Ao preencher visual_signature.signature_model_id, converter o ID textual para inteiro int64 somente após validar dígitos, intervalo e ausência de perda de precisão. Em JavaScript, não converter IDs grandes para Number sem esse cuidado.

Erros de aplicação

Upload

POST /flow/restful/application/upload

Enviar um PDF por chamada, antes de criar o processo. Preparar o arquivo final antes do envio; alterações posteriores no conteúdo exigem uma nova operação deliberada.

Resposta de sucesso — HTTP 200

{
  "status": {
    "code": 100,
    "name": "SUCCESS",
    "detail": "Operação realizada com sucesso"
  },
  "document_id": "11111111-1111-4111-8111-111111111111"
}

Um document_id já vinculado a um processo não pode ser usado em outro. Para um novo processo deliberado, fazer novo upload de cada PDF. Para retomar consulta ou download do processo existente, usar o process_id salvo.

Erros de aplicação

SignatureRequest

POST /flow/restful/application/signature-request

Cria um processo assíncrono com um ou mais PDFs já enviados e os signatários configurados. A criação pode enviar convites; uma resposta aceita não significa que os documentos já estejam assinados.

Terminologia: stakeholders são partes interessadas, distintas dos signatários; reminder_in configura lembretes; deadline define prazo geral ou individual; type escolhe a modalidade; visual_signature configura a apresentação visível.

Assinatura eletrônica não implica uso de certificado ICP-Brasil. Visibilidade não substitui verificação da assinatura. Não importar autenticação, transações ou regras comerciais do módulo CSS para este fluxo.

Corpo JSON

Itens de signers

Não combinar prazo geral com prazos individuais nem deixar prazos individuais parcialmente preenchidos. Confirmar com o produto a ordem efetiva de assinatura desejada; não inferir toda a sequência pelo array de signatários.

Itens de stakeholders

Configuração de visual_signature

Itens de visual_signature_detail

Modalidades visíveis: podem ocorrer respostas HTTP 500 com Visual signer definition not found for document: contract.pdf mesmo com estrutura aparentemente consistente. Preservar os IDs, modelo e payload redigido para diagnóstico. A causa não foi isolada; não reenviar automaticamente nem trocar a modalidade como tratamento do erro.

Exemplo mínimo de criação

{
  "title": "Contrato de integração",
  "type": "DIGITAL_SIGNATURE",
  "documents": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "signers": [
    {
      "name": "Participante",
      "email": "participante@example.invalid"
    }
  ],
  "callback_url": "https://integracao.example.invalid/flow/callback"
}

Exemplo estrutural de configuração visual

O corpo abaixo ilustra o vínculo de um PDF e um signatário; não garante a geometria final nem substitui a conferência da apresentação no PDF.

{
  "title": "Contrato com apresentação visual",
  "type": "DIGITAL_SIGNATURE_VISIBLE",
  "documents": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "signers": [
    {
      "name": "Participante",
      "email": "participante@example.invalid"
    }
  ],
  "callback_url": "https://integracao.example.invalid/flow/callback",
  "visual_signature": {
    "signature_model_id": 123,
    "visual_signature_detail": [
      {
        "document_id": "11111111-1111-4111-8111-111111111111",
        "signer_email": "participante@example.invalid",
        "page_number": 1,
        "x_position": 40,
        "y_position": 50
      }
    ]
  }
}

Resposta de sucesso — HTTP 200

{
  "status": {
    "code": 100,
    "name": "SUCCESS",
    "detail": "Operação realizada com sucesso"
  },
  "process_id": "22222222-2222-4222-8222-222222222222",
  "usage_alert": null
}

Erros de aplicação

Callback de conclusão

Preparar um receptor público antes da criação. Em desenvolvimento local, usar um receptor estável ou um túnel HTTPS até o coletor local e mantê-lo acessível durante o acompanhamento. Encerrar um túnel temporário impede novas notificações nessa URL, mas a consulta por ID permite retomar o processo.

A notificação de conclusão recebida é um POST JSON para callback_url, com os campos:

{
  "process_id": "22222222-2222-4222-8222-222222222222",
  "status": "FINALIZED_WITH_SUCCESS"
}

Correlacionar o ID com uma operação conhecida e consultar o processo autenticado antes de atualizar o estado local ou disparar efeitos de negócio. Tolerar notificações repetidas e concorrência com polling sem duplicar efeitos. Correlação de ID não autentica a origem. Autenticação/assinatura do evento, lista completa de estados, timeout, confirmação HTTP exigida e política de reentrega precisam ser acordados; não são definidos aqui.

ProcessStatus

GET /flow/restful/application/process?id=<process_id>

Consulta processos da conta. Para acompanhar uma operação conhecida, informar seu ID e selecionar exatamente o item correspondente na resposta.

Sem filtros, o período padrão documentado é dos últimos 15 dias. A ausência de um processo no resultado não comprova falha de criação e não autoriza reenviar o POST.

Resposta de sucesso — HTTP 200

{
  "status": {
    "code": 100,
    "name": "SUCCESS",
    "detail": "Operação realizada com sucesso"
  },
  "process_list": [
    {
      "title": "Contrato de integração",
      "id": "22222222-2222-4222-8222-222222222222",
      "status": "IN_PROGRESS",
      "documents": [
        "11111111-1111-4111-8111-111111111111"
      ],
      "signers": [
        {
          "name": "Participante",
          "email": "participante@example.invalid",
          "status": "SENT"
        }
      ]
    }
  ]
}

Depois da conclusão, o mesmo processo pode retornar status: FINALIZED_WITH_SUCCESS e participante status: SIGNED. Consultas e notificações podem ser repetidas; preservar estados desconhecidos para diagnóstico.

Exemplo de consulta sem resultados:

{
  "status": {
    "code": 100,
    "name": "SUCCESS",
    "detail": "Operação realizada com sucesso"
  },
  "process_list": null
}

Erros de aplicação

Download

GET /flow/restful/application/download/{process_id}

Baixa o resultado por process_id retornado em SignatureRequest. Substituir o parâmetro no path; ele é obrigatório e não é um document_id nem um parâmetro de query.

Resposta de sucesso — HTTP 200

Bytes de um arquivo ZIP com os arquivos do processo, não JSON, Base64 ou PDF único. Baixar automaticamente após confirmar FINALIZED_WITH_SUCCESS na consulta. Guardar o ZIP e verificar a integridade de seus membros conforme a integração.

Não presumir cópia original separada em todo ZIP de assinatura eletrônica; esse comportamento não foi confirmado. Conclusão operacional e integridade do ZIP não comprovam a validade criptográfica nem a apresentação visual das assinaturas nos PDFs.

Falha no download ou ao salvar o arquivo deve ser recuperada pelo mesmo process_id, sem repetir upload ou criação. O fim de uma espera local não cancela o processo remoto.

Erros HTTP