NAV
curl

Introdução

Bem-vindo ao guia de referências da API do Fast Notas! É através desta API que você irá integrar seu sistema para emissão/armazenamento de documentos.

Endpoints da API

Método Endpoint Descrição
GET /campany Retorna dados da empresa
GET /companies Retorna dados das empresas afiliadas à empresa parceira
GET /companies/:id Retorna uma empresa específica
POST /companies Cria uma empresa
DELETE /companies/:id Inativa uma empresa
PUT /companies/:id Atualiza os parâmetros de uma empresa
GET /customers Retorna todos clientes
POST /customers Cria um cliente
GET /customers/:id Retorna um cliente
PUT /customers/:id Atualiza os parâmetros
DELETE /customers/:id Deleta um cliente
GET /document_schemas Retorna todos os document_schemas de uma empresa
POST /document_schemas Cria um document_schema
GET /document_schemas/:id Retorna um document_schema
GET /document_schemas/:id/items Retorna items de um document_schema
PUT /document_schemas/:id Atualiza os parâmetros
DELETE /document_schemas/:id Inativa o document_schema
GET /items Retorna todos os items de uma empresa
POST /items Cria um item
GET /items/:id Retorna um item
PUT /items/:id Atualiza os parâmetros
DELETE /items/:id Inativa o item
GET /documents Retorna todos os documentos de uma empresa
POST /documents Cria um documento
GET /documents/:id/print Retorna o documento em formato para impressão (se houver)
GET /documents/:id Retorna um documento
GET /documents/:id/operations Retorna todas operações do documento
GET /documents/:id/assets Retorna todos assets do documento
DELETE /documents/:id Cancela um documento
GET /operations/:id Retorna uma operação
GET /operations/:id/transactions Retorna todas transações da operação
GET /transactions/:id Retorna uma transação
GET /assets/:id Retorna um asset
GET /assets/:id/download Retorna o asset em formato para impressão (se houver)

Autenticação

A autenticação na API é realizada através do método HTTP Basic, utilizando a chave da API no campo destinado ao usuário, sem a necessidade de informar uma senha. Vale lembrar que a API Fast Notas só pode ser utilizada através do protocolo HTTPS. Por motivos de segurança, requisições HTTP não serão redirecionadas automaticamente para o protocolo HTTPS.

Para fazer a autenticação, utilize o código abaixo em conjunto com o endpoint que deseja acessar:

curl https://api.fastnotas.com/v1/ \
  -u YOUR_API_KEY:

Authorization: Basic YOUR_API_KEY

Paginação

    curl -X GET https://api.fastnotas.com/v1/items/?page=2&per_page=5 \
      -u 'YOUR_API_KEY:'

Todos os recursos de listagem da API têm suporte à paginação. Para utilizar a paginação, você pode passar os parâmetros via QueryString:

Parâmetro Descrição
page:
Default: 1
Implementação de uma paginação de resultados do objeto
per_page:
Default:50
Retorna n objetos por página

Todas as requisições de listagem retornam os dados referentes à paginação através dos seguintes headers:

HTTP Header Descrição
Current-Page Página atual
Total-Pages Total de páginas
Per-Page Objetos por página

Busca

    curl -X GET https://api.fastnotas.com/v1/customers/?query=registry_code:CPF do cliente \
      -u 'YOUR_API_KEY:'

Todos os recursos de listagem da API têm suporte à busca. Você pode utilizar uma ou mais condições, opcionalmente agrupada por operadores (AND/and e OR/or) para criar uma consulta. Passe o parâmetro via QueryString:

Parâmetro Descrição
query Filtro a ser utilizado para obter os resultados do objeto:
query=<atributo><operador><valor>

Exemplo

query=operation_type=issue
atributo: “operation_type”
operador: “=” igual
valor: “issue”

Os seguintes operadores são suportados pela API:

Operador Descrição Exemplo
: Contém email:gmail.com
= Igual sequence=230
> Maior created_at>2017-01-11
>= Maior ou igual amount>=500
< Menor created_at<2017-01-11
<= Menor ou igual amount<=500
NOT/not/- Negação -status:active
( ) Agrupa condições (status:active AND name:paulo) OR name:mariana

Os campos que podem user usados nos filtros estão definidos dentro da documentação de cada recurso.

Webhooks

Durante a implementação da API poderão existir momentos em que você precisará aguardar alguma ação externa antes de prosseguir com seu processo. Suponha que você necessite confirmar a emissão de uma nota fiscal antes de emitir a cobrança. Uma prática desaconselhável seria, por exemplo, agendar uma consulta diária ao serviço de documentos do Fast Notas para verificar o status de emissao de todas as suas notas fiscais pendentes.

Além de desperdiçar recursos de processamento, você também sofreria com o atraso entre o momento real da emissão e da consulta do webservice. Isso poderia ser resolvido diminuindo o intervalo entre as consultas, porém dependendo do número de notas fiscais pendentes, este método tornaria-se inviável em pouco tempo.

Para resolver esse problema, inverte-se a responsabilidade da notificação: O Fast Notas avisará você quando alguma ação ocorrer. Este aviso é realizado através de um HTTP POST que o Fast Notas faz em uma URL que você pode configurar na plataforma. Estes avisos são chamados de webhooks.

Formato e método de envio

Todas as requisições geradas a partir de webhooks são efetuadas com o método POST, com o conteúdo no corpo (body) da requisição no formato JSON, incluindo os seguintes headers:

HTTP Header Descrição
Content-Type application/json; charset=UTF-8
User-Agent Fast-Notas-Hookshot/1.0

A plataforma espera que sua aplicação responda com o código HTTP 2XX (200, 201, etc) em no máximo 20 segundos. Códigos de redirecionamento (3XX) não serão seguidos e serão considerados como falha.

Retentativas

A plataforma Fast Notas irá efetuar 15 retentativas de envio caso seu sistema esteja fora do ar ou responda com um código HTTP diferente de 2xx. As retentativas são enviadas em intervalos progressivos durante aproximadamente 48 horas. Depois desse período a notificação é descartada.

Conteúdo da requisição

Como mencionado acima, o conteúdo da requisição estará contido em seu no corpo (body), no formato JSON.

O conteúdo do atributo data irá depender do tipo de evento enviado e respeitará o mesmo formato da API REST.

    {
      "event": {
        "type": "document_processing",
        "created_at": "2017-01-19T00:58:20.835Z",
        "data": {
          "document": {
            ...
          }
        }
      }
    }

Eventos

Evento type data
Documento em processamento document_processing document
Documento aguardando retorno externo document_waiting document
Documento emitido/arquivado com sucesso document_success document
Documento cancelado document_canceled document
Documento com erro document_error document
Documento rejeitado na emissão/arquivamento document_rejected document
Operação em processamento operation_processing operation
Operação aguardando retorno externo operation_waiting operation
Operação efetuada com sucesso operation_success operation
Operação com erro operation_error operation
Operação rejeitada operation_rejected operation
Arquivo disponível asset_avaliable asset

Rate Limit

Por padrão a API do Fast Notas possui um limite de 120 requisições por minuto por empresa. Para obter o status do limite, consulte os cabeçalhos abaixo no retorno de qualquer chamada à API: Os headers abaixo

Caso o limite de requisições seja atingido (Rate-Limit-Remaining igual à zero), a plataforma irá rejeitar a requisição seguinte e retornar o status HTTP status code 429 - Too Many Requests, incluindo o header Retry-After, que indica o número de segundos restantes para realizar uma nova tentativa.

O limite contempla todos os tipos de requisição, inclusive requisições inválidas do tipo HTTP status code 4xx.

Boas práticas

Em condições normais de operação dificilmente esse limite será atingido, porém más práticas de integração podem comprometer o limite rapidamente.

Evite polling

Polling é o nome do procedimento usado para buscar o status de determinada informação em intervalos de tempo consecutivos. Sabemos que é comum implementar rotinas diárias de consulta de status. Enquanto este procedimento funciona satisfatoriamente com um número baixo de registros, você poderá ultrapassar o limite de requisições caso o número de consultas aumente.

É justamente por isso que a plataforma Fast Notas oferece os webhooks. Em vez de gastar recursos computacionais com polling, configure a plataforma Fast Notas para avisar seu backend via POST imediatamente quando um evento ocorrer. Com isso você não desperdiça recursos e garante que sua plataforma estará com os dados sempre atualizados. Se você precisar de um tipo de webhook que ainda não esteja disponível, converse com nossa equipe e ficaremos felizes em criar um novo tipo de disparo que ajude você a se manter dentro do limite de requisições.

Use cache

Recursos que não são atualizados frequentemente podem ser armazenados em cache localmente. Por exemplo, em vez de efetuar uma requisição de listagem de documentos toda vez que um cliente quiser visualizar o status da sua nota fiscal, faça uma única consulta à API e armazene o resultado, configurando o tempo de expiração que julgar necessário. Soluções baseadas em memcache ou Redis funcionam muito bem nesses casos.

Companies

Através do endpoint /company é possível exibir todos os dados da sua empresa.

É essa entidade que possui a API_KEY, todas as outras entidades que forem criadas serão diretamente relacionadas a empresa. A informação é vinculada através do header de autenticação.

Caso não tenha uma API_KEY entre em contato com nosso atendimento: atendimento@fastnotas.com

Objeto company

Parâmetro Descrição
api_key
String
Chave de API da empresa
name
String
Nome da empresa
legal_name
String
Razão social
email
String
Email da empresa
registry_code
String
Documento da empresa(CNPJ)
status
Default: active
Define se a empresa está ativada ou não na API
address[country]
String
Código do país no formato ISO 3166-1 alpha-2. Exemplo: BR
address[zipcode]
String
Código Postal da empresa
address[state]
String
Código do estado no formato ISO 3166-2. Exemplo: SP
address[city]
String
Cidade da empresa
address[neighborhood]
String
Bairro da empresa
address[street]
String
Rua da empresa
address[number]
String
Número do endereço da empresa
address[additional_details]
String
Complemento do endereço da empresa
phone[phone_type]
String
Telefone residencial ou celular
phone[number]
String
Número do telefone da empresa sem separadores
phone[area_code]
String
Código de área do município
phone[country_code]
String
Código do país
phone[extension]
String
Ramal

Retornando os dados da sua empresa

Retorna os dados cadastrados da sua empresa.

GET https://api.fastnotas.com/v1/company

    curl -X GET https://api.fastnotas.com/v1/company
    -u 'YOUR_API_KEY:'

Exemplo de retorno em JSON:

{
    "id": "029821f2-e5e3-4b0b-af8f-a86f737d38d1",
    "name": "Teste Company",
    "legal_name": "Company of tests,",
    "email": "teste@teste.com",
    "registry_code": "77534615000122",
    "status": "active",
    "api_key": "YOUR_API_KEY",
    "webhook_url": "URL configurada na plataforma",
    "address": {
        "id": "1c05cf53-ad2c-4ae0-8f15-ef098b11186d",
        "neighborhood": "Vila Augusta",
        "street": "Maestro Zeferino Santana",
        "number": "132",
        "additional_details": "apto 1221",
        "zipcode": "18040010",
        "city": "Sorocaba",
        "state": "SP",
        "country": "BR"
    },
    "phone": {
        "phone_type": "landline",
        "country_code": null,
        "area_code": "11",
        "extension": null,
        "number": "59047394"
    }
}

Parceiros Fast Notas

Para cadastrar uma empresa afiliada, você deve ser uma empresa parceira do Fast Notas.

Gostaria de ser um parceiro? Entre em contato com nosso atendimento atendimento@fastnotas.com

Criando uma empresa

O cadastro deve ser feito utilizando um POST no endpoint /companies com os dados referentes do novo afiliado, utilizando a sua chave de API de parceiro. Retorna os dados da empresa criada.

POST https://api.fastnotas.com/v1/companies

  curl -X POST https://api.fastnotas.com/v1/companies \
    -u 'YOUR_API_KEY_PARTNER:' \
    -H 'Content-Type: application/json; charset=utf-8' \
    -d '{
          "name": "Teste Company",
          "legal_name": "Company of tests,",
          "email": "teste@teste.com",
          "registry_code": 53514882000170,
          "status": "active",
          "address": {
            "street": "Rua Albano Eugênio Dahmer", 
            "number": 325,
            "zipcode": "06710750",
            "neighborhood": "Pinus Park",
            "additional_details": "Conjunto 123",
            "city": "Cotia",
            "state": "SP",
            "country": "BR"
          },
          "phone": {
            "phone_type": "landline",
            "country_code": null,
            "area_code": "11",
            "extension": null,
            "number": "59047394"
          }
        }'

Exemplo de retorno em JSON:

{
    "id": "59e470fa-4c6d-47ee-9399-356c20b8e4af",
    "name": "Teste Company",
    "legal_name": "Company of tests,",
    "email": "teste@teste.com",
    "registry_code": "77534615000122",
    "status": "active",
    "phone": {
        "id": "e3fd4f8c-9253-4e5c-a6bb-f548158315e1",
        "phone_type": "landline",
        "country_code": null,
        "area_code": "11",
        "extension": null,
        "number": "59047394"
    },
    "api_key": "YOUR_API_KEY",
    "webhook_url": "URL configurada na plataforma",
    "partner": {
        "id": "223fb491-f663-4ac1-9247-df7af3abcbc1",
        "name": "Fast Notas - Partner",
        "legal_name": "Fast Notas - Partner",
        "email": "admin@partner.com",
        "registry_code": "56311864000189",
        "status": "active",
        "phone": null,
        "webhook_url": "URL configurada na plataforma",
        "partner": null
    },
    "address": {
        "id": "b9ca74ca-b774-461d-a049-ee23bc2e9570",
        "neighborhood": "Ipiranga",
        "street": "Rua dona leopoldina",
        "number": "825",
        "additional_details": "Cj. 12",
        "zipcode": "04278040",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR"
    }
} 
Parâmetro Descrição
name
String
Nome da empresa
legal_name
String
Razão social
email
String
Email da empresa
registry_code
String
Documento da empresa(CNPJ)
status
Default: active
Define se a empresa está ativada ou não na API
address[country]
String
Código do país no formato ISO 3166-1 alpha-2. Exemplo: BR
address[zipcode]
String
Código Postal da empresa
address[state]
String
Código do estado no formato ISO 3166-2. Exemplo: SP
address[city]
String
Cidade da empresa
address[neighborhood]
String
Bairro da empresa
address[street]
String
Rua da empresa
address[number]
String
Número do endereço da empresa
address[additional_details]
String
Complemento do endereço de uma empresa
phone[phone_type]
String
Telefone residencial ou celular
phone[number]
String
Número do telefone da empresa sem separadores
phone[area_code]
String
Código de área do município
phone[country_code]
String
Código do país
phone[extension]
String
Ramal




















Retornando as empresas afiliadas

Retorna um array que contém objetos das empresas afiliadas.

GET https://api.fastnotas.com/v1/companies/

    curl -X GET https://api.fastnotas.com/v1/companies/
    -u 'YOUR_API_KEY'

Exemplo de retorno em JSON:

[
    {
        "id": "bf49bdb3-d13d-418b-b991-65d606cf326e",
        "name": "Fast Notas - affiliates 2",
        "legal_name": "Fast Notas - affiliates 2",
        "email": "admin@affiliates2.com",
        "registry_code": "24513608000188",
        "status": "active",
        "phone": {
            "phone_type": "landline",
            "country_code": null,
            "area_code": "11",
            "extension": null,
            "number": "59047394"
        },
        "api_key": "YOUR_API_KEY",
        "webhook_url": null,
        "partner": {
            "id": "92fed7d5-0da6-4db9-9ac9-a365019e8707",
            "name": "Fast Notas - Partner",
            "legal_name": "Fast Notas - Partner",
            "email": "admin@partner.com",
            "registry_code": "56311864000189",
            "status": "active",
            "phone": null,
            "webhook_url": null,
            "partner": null
        },
        "address": {
            "id": "50dfbef7-bb57-4d43-910d-ee35c37b0b0a",
            "neighborhood": "Ipiranga",
            "street": "Rua dona leopoldina",
            "number": "825",
            "additional_details": "Cj. 12",
            "zipcode": "04278040",
            "city": "São Paulo",
            "state": "SP",
            "country": "BR"
        }
    },
    {
        "id": "6b652f4d-c657-4e38-b2d6-b15b98c1af00",
        "name": "Fast Notas - affiliates",
        "legal_name": "Fast Notas - affiliates",
        "email": "admin@affiliates.com",
        "registry_code": "91818231000162",
        "status": "active",
        "phone": {
            "phone_type": "landline",
            "country_code": null,
            "area_code": "11",
            "extension": null,
            "number": "59047394"
        },
        "api_key": "275aab6d-e37f-4d90-9bad-8b743e2cf725",
        "webhook_url": null,
        "partner": {
            "id": "92fed7d5-0da6-4db9-9ac9-a365019e8707",
            "name": "Fast Notas - Partner",
            "legal_name": "Fast Notas - Partner",
            "email": "admin@partner.com",
            "registry_code": "56311864000189",
            "status": "active",
            "phone": null,
            "webhook_url": null,
            "partner": null
        },
        "address": {
            "id": "50dfbef7-bb57-4d43-910d-ee35c37b0b0a",
            "neighborhood": "Ipiranga",
            "street": "Rua dona leopoldina",
            "number": "825",
            "additional_details": "Cj. 12",
            "zipcode": "04278040",
            "city": "São Paulo",
            "state": "SP",
            "country": "BR"
        }
    }
]




















Retornando uma empresa

Retorna objeto de empresa.

Parâmetro Descrição
:id

obrigatório

Id da empresa

GET https://api.fastnotas.com/v1/companies/{COMPANY_ID}

    curl -X GET https://api.fastnotas.com/v1/companies/{COMPANY_ID} 
    -u 'YOUR_API_KEY'

Exemplo de retorno em JSON:

{
    "id": "451203aa-7d60-425a-91ad-fc18b54f327b",
    "name": "Fast Notas - Partner",
    "legal_name": "Fast Notas - Partner",
    "email": "admin@partner.com",
    "registry_code": "56311864000189",
    "status": "active",
    "phone": {
        "phone_type": "landline",
        "country_code": null,
        "area_code": "11",
        "extension": null,
        "number": "59047394"
    },
    "api_key": "YOUR_API_KEY",
    "webhook_url": null,
    "partner": null,
    "address": {
        "id": "3b71ce21-65ed-4d34-8d75-068536eb7185",
        "neighborhood": "Ipiranga",
        "street": "Rua dona leopoldina",
        "number": "825",
        "additional_details": "Cj. 12",
        "zipcode": "04278040",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR"
    }
}

Atualizando um empresa

Atualiza a empresa solicitado e retorna com os parâmetros atualizados.

Este processo deve ser realizado utilizando os dados de autenticação da empresa afiliada.

Parâmetro Descrição
:id

obrigatório

Id da empresa
name
String
Nome da empresa
legal_name
String
Razão social
email
String
Email da empresa
registry_code
String
Documento da empresa(CNPJ)
status
Default: active
Define se a empresa está ativada ou não na API
address[country]
String
Código do país no formato ISO 3166-1 alpha-2. Exemplo: BR
address[zipcode]
String
Código Postal da empresa
address[state]
String
Código do estado no formato ISO 3166-2. Exemplo: SP
address[city]
String
Cidade da empresa
address[neighborhood]
String
Bairro da empresa
address[street]
String
Rua da empresa
address[number]
String
Número do endereço da empresa
address[additional_details]
String
Complemento do endereço da empresa
phone[phone_type]
String
Telefone residencial ou celular
phone[number]
String
Número do telefone da empresa sem separadores
phone[area_code]
String
Código de área do município
phone[country_code]
String
Código do país
phone[extension]
String
Ramal

PUT https://api.fastnotas.com/v1/companies/{COMPANY_ID}

    curl -X PUT https://api.fastnotas.com/v1/companies/{COMPANY_ID} \
      -u 'YOUR_API_KEY:' \
      -H 'Content-Type: application/json; charset=utf-8' \
      -d '{"id": "451203aa-7d60-425a-91ad-fc18b54f327b",
           "name": "Fast Notas - Partner",
           "legal_name": "Fast Notas - Partner",
           "email": "admin@partner.com",
           "registry_code": "56311864000189",
           "status": "active",
           "phone": {
             "phone_type": "landline",
             "country_code": null,
             "area_code": "11",
             "extension": null,
             "number": "59047394"
           },
           "api_key": "YOUR_API_KEY",
           "webhook_url": null,
           "partner": null,
           "address": {
             "id": "3b71ce21-65ed-4d34-8d75-068536eb7185",
             "neighborhood": "Ipiranga",
             "street": "Rua dona leopoldina",
             "number": "825",
             "additional_details": "Cj. 12",
             "zipcode": "04278040",
             "city": "São Paulo",
             "state": "SP",
             "country": "BR"
           }
         }'

Exemplo de retorno em JSON:

    {
      "id": "c7538d37-3ed1-4ee2-bc2d-f89afecb08d1",
      "name": "Carolina",
      "email": "novo_email@gmail.com",
      "registry_code": "11111111111",
      "external_code": "400",
      "status": "active",
      "phone": {
        "id": "bed01a89-2ff8-4ef2-8d0b-586a3bcbba3f",
        "phone_type": "landline",
        "country_code": "55",
        "area_code": "11",
        "extension": null,
        "number": "12345678",
        "company_id": "cdbe85f0-dc05-446c-aac8-af62b32e0d1a"
      },
      "address": {
        "id": "b7658863-988b-4e44-9632-a93a282dd41a",
        "neighborhood": "Rua Doutor Diogo de Faria",
        "street": "Rua Doutor Diogo de Faria",
        "number": "775",
        "additional_details": "Cj. 123",
        "zipcode": "04037003",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR"
      }
    }

Inativando uma empresa

Inativa a empresa solicitada.

Parâmetro Descrição
:id

obrigatório

Id da empresa que será inativada.

DELETE https://api.fastnotas.com/v1/companies/{COMPANY_ID}

    curl -X DELETE https://api.fastnotas.com/v1/companies/{COMPANY_ID} \
    -u 'YOUR_API_KEY:'

Customers

Representa uma pessoa física ou jurídica que será o tomador dos seus serviços ou o comprador dos produtos da sua empresa.

Através do endpoint /customers é possível listar, exibir, criar, atualizar e deletar clientes.

Objeto customer

Parâmetro Descrição
name
String
Nome do cliente
registry_code
String
Documento do cliente (CPF ou CNPJ)
email
String
Email do cliente
external_code
String
Referência opcional para controle do seu sistema
address[country]
String
Código do país no formato ISO 3166-1 alpha-2. Exemplo: BR
address[zipcode]
String
Código Postal do cliente
address[state]
String
Código do estado no formato ISO 3166-2. Exemplo: SP
address[city]
String
Cidade do cliente
address[neighborhood]
String
Bairro do cliente
address[street]
String
Rua do cliente
address[number]
String
Número do endereço do cliente
address[additional_details]
String
Complemento do endereço do cliente
phone[phone_type]
String
Telefone residencial ou celular
phone[number]
String
Número do telefone do cliente sem separadores
phone[area_code]
String
Código de área do município
phone[country_code]
String
Código do país
phone[extension]
String
Ramal

Criando um cliente

POST https://api.fastnotas.com/v1/customers

  curl -X POST https://api.fastnotas.com/v1/customers \
    -u 'YOUR_API_KEY:' \
    -H 'Content-Type: application/json; charset=utf-8' \
    -d '{
      "name": "Carolina",
      "registry_code": "1111111111",
      "email": "exemplo@gmail.com",
      "external_code": "400",
      "address": {
        "neighborhood": "Vila Clementino",
        "street": "Rua Doutor Diogo de Faria",
        "number": "775",
        "additional_details": "Cj. 123",
        "zipcode": "04037003",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR"
      },
      "phone": {
        "phone_type": "landline",
        "number": 12345678,
        "area_code": "11",
        "country_code": "55"
      }
    }'

Exemplo de retorno em JSON:

    {
      "id": "c7538d37-3ed1-4ee2-bc2d-f89afecb08d1",
      "name": "Carolina",
      "email": "exemplo@gmail.com",
      "external_code": "400",
      "registry_code": "11111111111",
      "status": "active",
      "phone": {
        "id": "bed01a89-2ff8-4ef2-8d0b-586a3bcbba3f",
        "phone_type": "landline",
        "country_code": "55",
        "area_code": "11",
        "extension": null,
        "number": "12345678",
        "company_id": "cdbe85f0-dc05-446c-aac8-af62b32e0d1a"
      },
      "address": {
        "id": "b7658863-988b-4e44-9632-a93a282dd41a",
        "neighborhood": "Rua Doutor Diogo de Faria",
        "street": "Rua Doutor Diogo de Faria",
        "number": "775",
        "additional_details": "Cj. 123",
        "zipcode": "04037003",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR"
      }
    }
Parâmetro Descrição
name Nome do cliente
registry_code Documento do cliente (CPF ou CNPJ)
email Email do cliente
external_code Referência opcional para controle do seu sistema
address[zipcode]

obrigatório

Código Postal do cliente
address[number]

obrigatório

Número do endereço do cliente
address[country] Código do país no formato ISO 3166-1 alpha-2. Exemplo: BR
address[state] Código do estado no formato ISO 3166-2. Exemplo: SP
address[city] Cidade do cliente
address[neighborhood] Bairro do cliente
address[street] Rua do cliente
address[additional_details] Complemento do endereço do cliente
phone[phone_type] Telefone residencial ou celular
phone[number] Número do telefone do cliente sem separadores
phone[area_code] Código de área do município
phone[country_code] Código do país
phone[extension] Ramal







Retornando um cliente

GET https://api.fastnotas.com/v1/customers/{CUSTOMER_ID}

    curl -X GET https://api.fastnotas.com/v1/customers/{CUSTOMER_ID}
    -u 'YOUR_API_KEY:'

Exemplo de retorno em JSON:

    {
      "id": "c7538d37-3ed1-4ee2-bc2d-f89afecb08d1",
      "name": "Carolina",
      "email": "exemplo@gmail.com",
      "registry_code": "11111111111",
      "external_code": "400",
      "status": "active",
      "phone": {
        "id": "bed01a89-2ff8-4ef2-8d0b-586a3bcbba3f",
        "phone_type": "landline",
        "country_code": "55",
        "area_code": "11",
        "extension": null,
        "number": "12345678",
        "company_id": "cdbe85f0-dc05-446c-aac8-af62b32e0d1a"
      },
      "address": {
        "id": "b7658863-988b-4e44-9632-a93a282dd41a",
        "neighborhood": "Rua Doutor Diogo de Faria",
        "street": "Rua Doutor Diogo de Faria",
        "number": "775",
        "additional_details": "Cj. 123",
        "zipcode": "04037003",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR"
      }
    }

Retorna os dados do cliente.

Parâmetro Descrição
:id

obrigatório

Id do cliente.




















Retornando clientes

Retorna um array que contém objetos de clientes.

Parâmetro Descrição
query Campos disponíveis para busca: name, email, registry_code, status, created_at

GET https://api.fastnotas.com/v1/customers/

    curl -X GET https://api.fastnotas.com/v1/customers/ \
    -u 'YOUR_API_KEY'

Exemplo de retorno em JSON:

    [
      {
        "id": "c7538d37-3ed1-4ee2-bc2d-f89afecb08d1",
        "name": "Carolina",
        "email": "exemplo@gmail.com",
        "registry_code": "11111111111",
        "external_code": "400",
        "status": "active",
        "phone": {
          "id": "bed01a89-2ff8-4ef2-8d0b-586a3bcbba3f",
          "phone_type": "landline",
          "country_code": "55",
          "area_code": "11",
          "extension": null,
          "number": "12345678",
          "company_id": "cdbe85f0-dc05-446c-aac8-af62b32e0d1a"
        },
        "address": {
          "id": "b7658863-988b-4e44-9632-a93a282dd41a",
          "neighborhood": "Rua Doutor Diogo de Faria",
          "street": "Rua Doutor Diogo de Faria",
          "number": "775",
          "additional_details": "Cj. 123",
          "zipcode": "04037003",
          "city": "São Paulo",
          "state": "SP",
          "country": "BR"
        }
      }
    ]

Atualizando um cliente

Atualiza o cliente solicitado e retorna com os parâmetros atualizados

Parâmetro Descrição
:id

obrigatório

Id do cliente

PUT https://api.fastnotas.com/v1/customers/{CUSTOMER_ID}

    curl -X PUT https://api.fastnotas.com/v1/customers/{CUSTOMER_ID} \
      -u 'YOUR_API_KEY:' \
      -H 'Content-Type: application/json; charset=utf-8' \
      -d '{
        "email": "novo_email@gmail.com"
      }'

Exemplo de retorno em JSON:

    {
      "id": "c7538d37-3ed1-4ee2-bc2d-f89afecb08d1",
      "name": "Carolina",
      "email": "novo_email@gmail.com",
      "registry_code": "11111111111",
      "external_code": "400",
      "status": "active",
      "phone": {
        "id": "bed01a89-2ff8-4ef2-8d0b-586a3bcbba3f",
        "phone_type": "landline",
        "country_code": "55",
        "area_code": "11",
        "extension": null,
        "number": "12345678",
        "company_id": "cdbe85f0-dc05-446c-aac8-af62b32e0d1a"
      },
      "address": {
        "id": "b7658863-988b-4e44-9632-a93a282dd41a",
        "neighborhood": "Rua Doutor Diogo de Faria",
        "street": "Rua Doutor Diogo de Faria",
        "number": "775",
        "additional_details": "Cj. 123",
        "zipcode": "04037003",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR"
      }
    }

Deletando um cliente

Deleta o cliente solicitado.

Parâmetro Descrição
:id

obrigatório

Id do cliente que será deletado.

DELETE https://api.fastnotas.com/v1/customers/{CUSTOMER_ID}

    curl -X DELETE https://api.fastnotas.com/v1/customers/{CUSTOMER_ID} \
    -u 'YOUR_API_KEY:'

Document schemas

Utilize este método para cadastrar o tipo de documento que você deseja emitir/arquivar.

Através do endpoint /document_schemas é possível listar, exibir, criar, atualizar e deletar tipos de documentos.

Objeto document_schema

Parâmetro Descrição
name
String
Nome do documento.
code
String
Código para identificação (Por exemplo:“NFS-e”)
type
String
Tipo de documento que deve ser emitido/arquivado
Tipos: Invoice::Nfse
status
Default: active
Define se o tipo de documento está ativado ou não na API
serie

Default: FASTN

Série para a identificação dos documentos de determinado tipo de documento
sequence
Int
Número sequencial do último documento emitido/armazenado desse tipo
credentials
[attributes]
Hash
Consulte a seção de configurações para cada tipo de
document_schema
parameters
[attributes]
Hash
Consulte a seção de configurações de configurações para cada tipo de
document_schema

Criando um tipo de documento

POST https://api.fastnotas.com/v1/document_schemas

  curl -X POST https://api.fastnotas.com/v1/document_schemas \
    -u 'YOUR_API_KEY:' \
    -H 'Content-Type: application/json; charset=utf-8' \
    -d '{
      "name": "Nota fiscal de serviço",
      "code": "NFS-e",
      "type": "Invoice::Nfse",
      "credentials": {
        "attribute_1": "value",
        "attribute_2": "value",
        "attribute_3": "value"
      },
      "parameters": {
        "attribute_4": "value"
      }
    }'
Parâmetro Descrição
name

obrigatório

Nome do documento
code

obrigatório

Código para identificação (Por exemplo:“NFS-e”)
type

obrigatório

Aceita o tipo do tipo do documento
Tipos: Invoice::Nfse
serie

Default: FASTN

Série para a identificação do documento
sequence

Default: 1

Número sequencial da série
credentials
[attributes]

obrigatório

Consulte a seção de configurações para cada tipo de
document_schema
parameters
[attributes]
Hash
Consulte a seção de configurações para cada tipo de
document_schema

Caso seja necessário enviar arquivos para o seu tipo de documento, utilize o header abaixo:

HTTP Header Valor
Content-Type multipart/form-data







Retornando um tipo de documento

GET https://api.fastnotas.com/v1/document_schemas/{DOCUMENT_SCHEMA_ID}

    curl -X GET https://api.fastnotas.com/v1/document_schemas/{DOCUMENT_SCHEMA_ID} \
    -u 'YOUR_API_KEY:'

Exemplo de retorno em JSON:

    {
      "id": "b7658863-988b-4e44-9632-a93a282dd41a",
      "name": "Nota fiscal de serviço",
      "code": "NFS-e",
      "type": "Invoice::Nfse",
      "status": "active",
      "serie": "FASTN",
      "sequence": 1,
      "credentials": {
        "certificate": "[FILTERED]",
        "password": "[FILTERED]",
        "expiration_date": "2020-12-30"
      },
      "parameters": {
        "municipal_registration": "12211"
      }
    }

Retorna os dados do tipo de documento solicitado.

Parâmetro Descrição
:id

obrigatório

Id do tipo de documento.

Retornando tipos de documento

GET https://api.fastnotas.com/v1/document_schemas/

    curl -X GET https://api.fastnotas.com/v1/document_schemas \
    -u 'YOUR_API_KEY:'

Exemplo de retorno em JSON:

    [
      {
        "id": "b7658863-988b-4e44-9632-a93a282dd41a",
        "name": "Nota fiscal de serviço",
        "code": "NFS-e",
        "type": "Invoice::Nfse",
        "status": "active",
        "serie": "FASTN",
        "sequence": 1,
        "credentials": {
          "certificate": "[FILTERED]",
          "password": "[FILTERED]",
          "expiration_date": "2020-12-30"
        },
        "parameters": {
          "municipal_registration": "12211"
        }
      }
    ]

Retorna um array que contém objetos de tipo de documento.

Atualizando um tipo de documento

PUT https://api.fastnotas.com/v1/document_schema/{DOCUMENT_SCHEMA_ID}

  curl -X PUT https://api.fastnotas.com/v1/document_schemas/{DOCUMENT_SCHEMA_ID} \
  -u 'YOUR_API_KEY:' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "name": "Tipo de Documento para NFS-e",
    "code": "invoice_nfse"
  }'

Exemplo de retorno JSON:

    {
      "id": "b7658863-988b-4e44-9632-a93a282dd41a",
      "name": "Tipo de Documento para NFS-e",
      "code": "invoice_nfse",
      "type": "Invoice::Nfse",
      "status": "active",
      "sequence": 1,
      "credentials": {
        "certificate": "[FILTERED]",
        "password": "[FILTERED]",
        "expiration_date": "2020-12-30"
      },
      "parameters": {
        "municipal_registration": "12211"
      }
    }

Atualiza o tipo de documento solicitado e retorna com os parâmetros atualizados.

Parâmetro Descrição
:id

obrigatório

Id do tipo de documento.

Deletando um tipo de documento

Deleta o tipo de documento solicitado.

Parâmetro Descrição
:id

obrigatório

Id do tipo de documento

DELETE https://api.fastnotas.com/v1/document_schemas/{DOCUMENT_schema_ID}

    curl -X DELETE https://api.fastnotas.com/v1/document_schemas/{DOCUMENT_schema_ID} \
    -u 'YOUR_API_KEY:'

Retornando items de um tipo de documento

GET https://api.fastnotas.com/v1/document_schemas/{DOCUMENT_SCHEMA_ID}/items

    curl -X GET https://api.fastnotas.com/v1/document_schemas/{DOCUMENT_SCHEMA_ID}/items \
    -u 'YOUR_API_KEY:'

Exemplo de retorno em JSON:

  [
    {
      "id": "dac22e14-351d-49b9-bed3-18c50ba81adf",
      "name": "emissão de nota fiscal",
      "description": "teste",
      "amount": 345.5,
      "document_schema_id": "3f6fa6a9-6fe7-4464-aa7f-8ee302580537",
      "setting": {
        "taxes": {
          "iss": "3.1"
        },
        "parameters": {
          "service_code": "123"
        }
      }
    }
  ]

Com a rota /document_schemas/:id/items é possível ver todos os itens de um tipo de documento.

Parâmetro Descrição
:id

obrigatório

Id do tipo de documento.

Items

Utilize este método para cadastrar um item de acordo com um tipo de documento.

Através do endpoint /items, é possível listar, exibir, criar, atualizar e deletar itens.

Obs.: Os parâmetros settings utilizados em todos os exemplos são referentes a NFS-e emitidas em São Paulo(SP), consulte a seção de configurações para visualizar quais os atributos são necessários para o documento que você vai emitir.



Objeto item

Parâmetro Descrição
name
String
Nome do produto/serviço
description
String
Descrição do produto/serviço
status
Default: active
Define se o item está ativado ou não na API
amount
Float
Valor do produto/serviço
document_schema
Hash
Representação da entidade document_schema
settings[]
[attributes]
Hash
Consulte a seção de configurações

Criando um item

POST https://api.fastnotas.com/v1/items

    curl -X POST  https://api.fastnotas.com/v1/items/ \
      -u 'YOUR_API_KEY:' \
      -H 'Content-Type: application/json; charset=utf-8' \
     -d '{
      "name":"Serviço de emissão de notas fiscais",
      "description":"Software as a service que emite notas",
      "amount": 345.5,
      "setting": {
        "taxes": {
          "iss":"3.1"
        },
        "parameters": {
          "service_code":"123"
        }
      },
      "document_schema_id": "b7658863-988b-4e44-9632-a93a282dd41a"
    }'

Exemplo de retorno em JSON:

    {
      "id":"73831b4e-7c90-465a-bfa5-5114da66bb60",
      "name":"Serviço de emissão de notas fiscais",
      "description":"Software as a service que emite notas",
      "amount":345.5,
      "setting": {
        "taxes": {
          "iss":"3.1"
        },
        "parameters": {
          "service_code":"123"
        }
      },
      "document_schema_id": "b7658863-988b-4e44-9632-a93a282dd41a"
    }




Parâmetro Descrição
name

obrigatório

Nome do produto/serviço
description

obrigatório

Descrição do produto/serviço
amount

obrigatório

Valor do produto/serviço
document_schema_id

obrigatório

Id do esquema de documento
settings[]
[attributes]

obrigatório

Consulte a seção de configurações






Retornando um item

GET https://api.fastnotas.com/v1/items/{ITEM_ID}

    curl -X GET https://api.fastnotas.com/v1/items/{ITEM_ID} \
    -u 'YOUR_API_KEY:'

Exemplo de retorno em JSON:

    {
      "id":"73831b4e-7c90-465a-bfa5-5114da66bb60",
      "name":"Serviço de emissão de notas fiscais",
      "description":"Software as a service que emite notas",
      "amount":345.5,
      "setting": {
        "taxes": {
          "iss":"3.1"
        },
        "parameters": {
          "service_code":"123"
        }
      },
      "document_schema_id": "b7658863-988b-4e44-9632-a93a282dd41a"
    }

Retorna os dados do item solicitado.

Parâmetro Descrição
:id

obrigatório

Id do item criado




















Retornando itens

Retorna um array que contém objetos de item.

Parâmetro Descrição
query Campos disponíveis para busca: name, description, amount, created_at

GET https://api.fastnotas.com/v1/items/

    curl -X GET https://api.fastnotas.com/v1/items/ \
    -u 'YOUR_API_KEY'

Exemplo de retorno em JSON:

    [
      {
        "id":"73831b4e-7c90-465a-bfa5-5114da66bb60",
        "name":"Serviço de emissão de notas fiscais",
        "description":"Software as a service que emite notas",
        "amount":345.5,
        "setting": {
          "taxes": {
            "iss":"3.1"
          },
          "parameters": {
            "service_code":"123"
          }
        },
        "document_schema_id": "b7658863-988b-4e44-9632-a93a282dd41a"
      }
    ]

Atualizando um item

Atualiza o item solicitado e retorna com os parâmetros atualizados

Parâmetro Descrição
:id

obrigatório

Id do item criado

PUT https://api.fastnotas.com/v1/items/{ITEM_ID}

    curl -X PUT https://api.fastnotas.com/v1/items/{ITEM_ID} \
      -u 'YOUR_API_KEY:' \
      -H 'Content-Type: application/json; charset=utf-8' \
      -d '{
        "amount": 450
      }'
    [
      {
        "id":"73831b4e-7c90-465a-bfa5-5114da66bb60",
        "name":"Serviço de emissão de notas fiscais",
        "description":"Software as a service que emite notas",
        "amount":450.0,
        "setting": {
          "taxes": {
            "iss":"3.1"
          },
          "parameters": {
            "service_code":"123"
          }
        },
        "document_schema_id": "b7658863-988b-4e44-9632-a93a282dd41a"
      }
    ]

Deletando um item

Deleta o item solicitado.

Parâmetro Descrição
:id

obrigatório

Id do item que será deletado

DELETE https://api.fastnotas.com/v1/items/{ITEM_ID}

    curl -X DELETE https://api.fastnotas.com/v1/items/{ITEM_ID} \
    -u 'YOUR_API_KEY:'

Documents

Representa um documento fiscal.

Para emitir um documento utilize o endpoint /documents. É possível listar, exibir e criar documentos.

Objeto document

Parâmetro Descrição
amount
Float
Valor total dos itens do documento
status
Default: pending
Consulte a lista de status possíveis do documento
last_operation
Hash
Última operação do documento
last_operation[last_transaction]
Hash
Última transação da operação do documento
sequence
Int
Número sequencial do documento
document_schema
Hash
Representação da entidade document_schema
customer
Hash
Representação da entidade customer
document_items
Array
Produtos/serviços prestados do documento
print_url
String
Link para download do documento
issue_on
String
Data de emissão do documento no formato ISO 8601

Status do documento

Quando um documento é criado, o status inicial é pending . Ele pode ter os seguintes status:

Criando um documento

POST https://api.fastnotas.com/v1/documents/

  curl -X POST  https://api.fastnotas.com/v1/documents/ \
    -u 'YOUR_API_KEY:' \
    -H 'Content-Type: application/json; charset=utf-8' \
    -d '{
      "document_schema_id": "d0b0d7ef-cb07-42af-9f74-ab17236c82c9",
      "customer_id": "1a925c53-b415-448f-8356-46d33bc2c431",
      "issue_on": "2017-07-15",
      "document_items": [{
        "item_id": "a60dd677-5c88-4963-9b08-f48e5899a11f",
        "amount": "49.9"
      }]
    }'

Exemplo de retorno em JSON:

  [
    {
      "id": "728a124f-99cd-409a-bd13-b50685778977",
      "company_id": "6f262be2-3f9f-4d3e-95c6-8bd4762f919d",
      "amount": 345.5,
      "sequence": 1,
      "status": "processing",
      "issue_on": "2017-07-15",
      "last_operation": {
        "id": "831fb818-704d-484f-8c8f-8fadf361b26b",
        "operation_type": "issue",
        "status": "processing",
        "print_url": "https://api.fastnotas.com/v1/documents/728a124f-99cd-409a-bd13-b50685778977/print",
        "created_at": "2016-11-18T13:09:27.800Z",
        "updated_at": "2016-11-18T13:09:27.851Z",
        "last_transaction": {
          "id": "d03cd204-cba8-4ae0-b2ca-548e0ceed86d",
          "status": "processing",
          "messages": null,
          "response_fields": null,
          "created_at": "2016-11-18T13:09:27.896Z",
          "updated_at": "2016-11-18T13:09:27.905Z"
        }
      },
      "document_items": [
        {
          "id": "a60dd677-5c88-4963-9b08-f48e5899a11f",
          "name": "item",
          "description": "item description",
          "amount": 49.90,
          "item_id": "5643de81-e19e-4545-b766-1d80838a744b",
          "settings": {
            "taxes": {
              "iss": "3.1"
            },
            "parameters": {
              "service_code": "123"
            }
          }
        }
      ],
      "customer": {
        "id": "1a925c53-b415-448f-8356-46d33bc2c431",
        "name": "Carolina",
        "email": "exemplo@fastnotas.com",
        "registry_code": "11111111111",
        "status": "active",
        "phone": {
          "id": "3d630e5a-620d-4cb1-b9ad-d4f8aeabf5ba",
          "phone_type": "mobile",
          "country_code": null,
          "area_code": "11",
          "extension": null,
          "number": "43214321",
          "company_id": "6f262be2-3f9f-4d3e-95c6-8bd4762f919d"
        }
      },
      "document_schema": {
       "id": "d0b0d7ef-cb07-42af-9f74-ab17236c82c9",
        "name": "nota fiscal de serviço",
        "code": "nfs-e",
        "type": "DocumentSchema::Invoice::Nfse::Sp::SaoPaulo",
        "sequence": 1,
        "credentials": {
          "certificate_key": "[FILTERED]",
          "expiration_date": "2017-06-24 15:54:00 UTC",
          "certificate": "[FILTERED]"
        },
        "status": "active"
      }
    }
  ]
Parâmetro Descrição
customer_id

obrigatório

Id do cliente
document_schema_id

obrigatório

Id do esquema de documento
document_items[][item_id]

obrigatório

Id do produto/serviço prestado
document_items[][attributes] Você pode sobrescrever os valores padrões do item

Retornando um documento

GET https://api.fastnotas.com/v1/documents/{DOCUMENT_ID}

    curl -X GET https://api.fastnotas.com/v1/documents/{DOCUMENT_ID} \
    -u 'YOUR_API_KEY:'

Exemplo de retorno em JSON:

  [
    {
      "id": "728a124f-99cd-409a-bd13-b50685778977",
      "company_id": "6f262be2-3f9f-4d3e-95c6-8bd4762f919d",
      "amount": 345.5,
      "sequence": 1,
      "status": "processing",
      "issue_on": "2017-07-15",
      "print_url": "https://api.fastnotas.com/v1/documents/728a124f-99cd-409a-bd13-b50685778977/print",
      "last_operation": {
        "id": "831fb818-704d-484f-8c8f-8fadf361b26b",
        "operation_type": "issue",
        "status": "processing",
        "created_at": "2016-11-18T13:09:27.800Z",
        "updated_at": "2016-11-18T13:09:27.851Z",
        "last_transaction": {
          "id": "d03cd204-cba8-4ae0-b2ca-548e0ceed86d",
          "status": "processing",
          "messages": null,
          "response_fields": null,
          "created_at": "2016-11-18T13:09:27.896Z",
          "updated_at": "2016-11-18T13:09:27.905Z"
        }
      },
      "document_items": [
        {
          "id": "daa356f5-d7ec-4a42-b99b-4ffc7db39c16",
          "name": "item",
          "description": "item description",
          "amount": 345.5,
          "item_id": "5643de81-e19e-4545-b766-1d80838a744b",
          "settings": {
            "taxes": {
              "iss": "3.1"
            },
            "parameters": {
              "service_code": "123"
            }
          }
        }
      ],
      "customer": {
        "id": "1a925c53-b415-448f-8356-46d33bc2c431",
        "name": "Carolina",
        "email": "exemplo@fastnotas.com",
        "registry_code": "11111111111",
        "status": "active",
        "phone": {
          "id": "3d630e5a-620d-4cb1-b9ad-d4f8aeabf5ba",
          "phone_type": "mobile",
          "country_code": null,
          "area_code": "11",
          "extension": null,
          "number": "43214321",
          "company_id": "6f262be2-3f9f-4d3e-95c6-8bd4762f919d"
        }
      },
      "document_schema": {
       "id": "d0b0d7ef-cb07-42af-9f74-ab17236c82c9",
        "name": "nota fiscal de serviço",
        "code": "nfs-e",
        "type": "DocumentSchema::Invoice::Nfse::Sp::SaoPaulo",
        "sequence": 1,
        "credentials": {
          "certificate_key": "[FILTERED]",
          "expiration_date": "2017-06-24 15:54:00 UTC",
          "certificate": "[FILTERED]"
        },
        "status": "active"
      }
    }
  ]

Retorna os dados do documento solicitado.

Parâmetro Descrição
:id

obrigatório

Id do documento criado

Retornando documentos

Retorna um array que contém objetos do documento.

Parâmetro Descrição
query Campos disponíveis para busca: amount, status, sequence, serie, created_at

GET https://api.fastnotas.com/v1/documents/

    curl -X GET https://api.fastnotas.com/v1/documents/ \
    -u 'YOUR_API_KEY'

Exemplo de retorno em JSON:

    [
      {
        "id": "40d34041-d8f5-4ff1-8c2c-8bf21dcea35f",
        "company_id": "cced3716-0288-4371-9f4d-027d9a62ddef",
        "amount": 150.5,
        "issue_on": "2017-07-15",
        "customer": {
          "id": "cec6d637-599f-4ea5-9672-ad85acb95ebf",
          "name": "Carolina",
          "email": "exemplo@fastnotas.com",
          "registry_code": "11111111111",
          "status": "active",
          "print_url": "https://api.fastnotas.com/v1/documents/728a124f-99cd-409a-bd13-b50685778977/print",
          "phone": {
            "id": "4ad34b22-4c43-40b4-a267-3577cb693fc4",
            "phone_type": "mobile",
            "country_code": null,
            "area_code": "11",
            "extension": null,
            "number": "43214321",
            "company_id": "cced3716-0288-4371-9f4d-027d9a62ddef"
          }
        },
        "document_schema": {
          "id": "d0b0d7ef-cb07-42af-9f74-ab17236c82c9",
          "name": "nota fiscal de serviço",
          "code": "nfs-e",
          "type": "DocumentSchema::Invoice::Nfse::Sp::SaoPaulo",
          "sequence": 1,
          "credentials": {
            "certificate_key": "[FILTERED]",
            "expiration_date": "2017-06-24 15:54:00 UTC",
            "certificate": "[FILTERED]"
          },
          "status": "active"
        },
        "document_items": [
          {
            "id": "428b4110-0368-46a3-84b2-769864868a47",
            "name": "Serviço de emissão de notas fiscais",
            "description": "Software as a service que emite notas",
            "amount": 150.5,
            "item_id": "64479c2c-2f86-4aab-ac7a-6ee8afd0e483",
            "settings": {
              "taxes": {
                "iss": "3.1"
              },
              "parameters": {
                "service_code": "123"
              }
            }
          }
        ]
      }
    ]

Cancelando um documento

Cancela o documento solicitado.

Parâmetro Descrição
:id

obrigatório

Id do documento criado

DELETE https://api.fastnotas.com/v1/documents/{DOCUMENT_ID}

  curl -X DELETE https://api.fastnotas.com/v1/documents/{DOCUMENT_ID} \
  -u 'YOUR_API_KEY:'

Imprimindo um documento

Retorna o documento em formato para impressão (se houver).

Caso o asset do tipo print para este documento não esteja com o status available, o sistema devolverá um arquivo temporário contendo todas as informações e seguindo o padrão do arquivo original.

Parâmetro Descrição
:id

obrigatório

Id do documento criado

GET https://api.fastnotas.com/v1/documents/{DOCUMENT_ID}/print

  curl -X GET https://api.fastnotas.com/v1/documents/{DOCUMENT_ID}/print

Obtendo operações do documento

GET https://api.fastnotas.com/v1/documents/{DOCUMENT_ID}/operations

    curl -X GET https://api.fastnotas.com/v1/documents/{DOCUMENT_ID}/operations \
    -u 'YOUR_API_KEY'

Exemplo de retorno em JSON:

  [
    {
      "id": "831fb818-704d-484f-8c8f-8fadf361b26b",
      "operation_type": "issue",
      "status": "processing",
      "created_at": "2016-11-18T13:09:27.800Z",
      "updated_at": "2016-11-18T13:09:27.851Z",
      "last_transaction": {
        "id": "d03cd204-cba8-4ae0-b2ca-548e0ceed86d",
        "status": "processing",
        "messages": null,
        "response_fields": null,
        "created_at": "2016-11-18T13:09:27.896Z",
        "updated_at": "2016-11-18T13:09:27.905Z"
      },
      "document": {
        "id": "728a124f-99cd-409a-bd13-b50685778977",
        "company_id": "6f262be2-3f9f-4d3e-95c6-8bd4762f919d",
        "amount": 345.5,
        "sequence": 1,
        "status": "processing",
        "issue_on": "2017-07-15",
        "last_operation": {
          "id": "831fb818-704d-484f-8c8f-8fadf361b26b",
          "operation_type": "issue",
          "status": "processing",
          "created_at": "2016-11-18T13:09:27.800Z",
          "updated_at": "2016-11-18T13:09:27.851Z",
          "last_transaction": {
            "id": "d03cd204-cba8-4ae0-b2ca-548e0ceed86d",
            "status": "processing",
            "messages": null,
            "response_fields": null,
            "created_at": "2016-11-18T13:09:27.896Z",
            "updated_at": "2016-11-18T13:09:27.905Z"
          }
        }
      }
    }
  ]

Com a rota /documents/:id/operations é possível ver todas as operações de um documento.

Parâmetro Descrição
:id

obrigatório

Id do documento criado
query Campos disponíveis para busca: operation_type, created_at, status

Obtendo assets do documento

GET https://api.fastnotas.com/v1/documents/{DOCUMENT_ID}/assets

    curl -X GET https://api.fastnotas.com/v1/documents/{DOCUMENT_ID}/assets \
    -u 'YOUR_API_KEY'

Exemplo de retorno em JSON:

  [
    {
      "id": "a8ac430a-ea19-46cf-9617-ff8f47ef1260",
      "status": "available",
      "type": "Asset::Print",
      "created_at": "2017-06-13T11:59:47.686Z",
      "updated_at": "2017-06-13T11:59:48.787Z",
      "document": {
        "id": "d18abeb1-185e-4fa7-ba22-6b336d9c3ddd",
        "customer_id": "dacdf315-aff4-4710-84c5-09c272f1a841",
        "company_id": "b94888a8-ba9a-493a-8373-ccd0202784c6",
        "document_schema_id": "8479b00b-f06e-4f85-b9f5-98a240d1f90d",
        "created_at": "2017-06-13T11:59:44.518Z",
        "updated_at": "2017-06-13T11:59:47.607Z",
        "issue_on": "2017-07-15",
        "status": "success",
        "amount": 1985.52,
        "sequence": 126,
        "serie": "FASTN"
      }
    },
    {
      "id": "551e45ba-1b1c-4872-b383-31a98966ae8b",
      "status": "available",
      "type": "Asset::XmlRequest",
      "created_at": "2017-06-13T11:59:47.664Z",
      "updated_at": "2017-06-13T11:59:47.800Z",
      "document": {
        "id": "d18abeb1-185e-4fa7-ba22-6b336d9c3ddd",
        "customer_id": "dacdf315-aff4-4710-84c5-09c272f1a841",
        "company_id": "b94888a8-ba9a-493a-8373-ccd0202784c6",
        "document_schema_id": "8479b00b-f06e-4f85-b9f5-98a240d1f90d",
        "created_at": "2017-06-13T11:59:44.518Z",
        "updated_at": "2017-06-13T11:59:47.607Z",
        "issue_on": "2017-07-15",
        "status": "success",
        "amount": 1985.52,
        "sequence": 126,
        "serie": "FASTN"
      }
    }
  ]

Com a rota /documents/:id/assets é possível ver todos os assets de um documento.

Parâmetro Descrição
:id

obrigatório

Id do documento criado
query Campos disponíveis para busca: status, type, created_at, updated_at

Operations

Objeto operation

Este objeto representa a operação de emissão/cancelamento do documento.

Parâmetro Descrição
operation_type
Symbol
Tipo de operação
Valores: issue e cancel
status
Default: pending
Consulte a lista de status possíveis da operação
document
[attributes]

Hash
Representação da entidade document

Status da operação

Quando uma operação é criada, o status inicial é pending . Ela pode ter os seguintes status:

Retornando uma operação

GET https://api.fastnotas.com/v1/operations/{OPERATION_ID}

    curl -X GET https://api.fastnotas.com/v1/operations/{OPERATION_ID} \
    -u 'YOUR_API_KEY:'

Exemplo de retorno em JSON:

    {
      "id": "831fb818-704d-484f-8c8f-8fadf361b26b",
      "operation_type": "issue",
      "status": "processing",
      "created_at": "2016-11-18T13:09:27.800Z",
      "updated_at": "2016-11-18T13:09:27.851Z",
      "last_transaction": {
        "id": "d03cd204-cba8-4ae0-b2ca-548e0ceed86d",
        "status": "processing",
        "messages": null,
        "response_fields": null,
        "created_at": "2016-11-18T13:09:27.896Z",
        "updated_at": "2016-11-18T13:09:27.905Z"
      },
      "document": {
        "id": "728a124f-99cd-409a-bd13-b50685778977",
        "company_id": "6f262be2-3f9f-4d3e-95c6-8bd4762f919d",
        "amount": 345.5,
        "sequence": 1,
        "status": "processing",
        "last_operation": {
          "id": "831fb818-704d-484f-8c8f-8fadf361b26b",
          "operation_type": "issue",
          "status": "processing",
          "created_at": "2016-11-18T13:09:27.800Z",
          "updated_at": "2016-11-18T13:09:27.851Z",
          "last_transaction": {
            "id": "d03cd204-cba8-4ae0-b2ca-548e0ceed86d",
            "status": "processing",
            "messages": null,
            "response_fields": null,
            "created_at": "2016-11-18T13:09:27.896Z",
            "updated_at": "2016-11-18T13:09:27.905Z"
          }
        }
      }
    }

Retorna os dados da operação solicitada.

Parâmetro Descrição
:id

obrigatório

Id da operação criada

Obtendo transações de uma operação

GET https://api.fastnotas.com/v1/operations/{OPERATION_ID}/transactions

    curl -X GET https://api.fastnotas.com/v1/operations/{OPERATION_ID}/transactions \
    -u 'YOUR_API_KEY:'

Exemplo de retorno em JSON:

  [
    {
      "id": "d03cd204-cba8-4ae0-b2ca-548e0ceed86d",
      "status": "processing",
      "messages": null,
      "response_fields": null,
      "created_at": "2016-11-18T13:09:27.896Z",
      "updated_at": "2016-11-18T13:09:27.905Z"
    }
  ]

Com a rota /operations/:id/transactions é possível ver todas as transações de uma operação.

Parâmetro Descrição
:id

obrigatório

Id da operação criada
query Campos disponíveis para busca: status, created_at

Transactions

Objeto transaction

Este objeto representa uma transação dentro da operação de emissão/cancelamento.

Parâmetro Descrição
status
Default: pending
Consulte a lista de status possíveis da transação
messages
Hash
Mensagens da transação
response_fields
Hash
Atributos de resposta do serviço de emissão/armazenamento do documento

Status da transação

Quando uma transação é criada, o status inicial é pending . Ela pode ter os seguintes status:

Retornando uma transação

GET https://api.fastnotas.com/v1/transactions/{TRANSACTION_ID}

    curl -X GET https://api.fastnotas.com/v1/transactions/{TRANSACTION_ID} \
    -u 'YOUR_API_KEY:'

Exemplo de retorno em JSON:

    {
      "id": "d03cd204-cba8-4ae0-b2ca-548e0ceed86d",
      "status": "processing",
      "messages": null,
      "response_fields": null,
      "created_at": "2016-11-18T13:09:27.896Z",
      "updated_at": "2016-11-18T13:09:27.905Z"
    }

Retorna os dados da transação solicitada.

Parâmetro Descrição
:id

obrigatório

Id da transação criada

Assets

Os assets são as entidades que representam os arquivos relacionados a um documento. Exemplo: Arquivo para impressão do documento, XML’s e TXT’s que contém informações de comunicação com órgãos emissores e etc.

Objeto asset

Este objeto representa um asset relacionado ao documento, operação e transação.

Parâmetro Descrição
status
Default: pending
Consulte a lista de status possíveis do asset
type
Hash
Consulte a lista de tipos possíveis do asset
document
Hash
Representação da entidade Document
operation
Hash
Representação da entidade Operation
transaction
Hash
Representação da entidade Transaction

Status do asset

Quando um asset é criado, o status inicial é pending . Ele pode ter os seguintes status:

Tipos do asset

Ele pode ter os seguintes tipos:

Retornando um asset

GET https://api.fastnotas.com/v1/assets/{ASSET_ID}

    curl -X GET https://api.fastnotas.com/v1/assets/{ASSET_ID} \
    -u 'YOUR_API_KEY:'

Exemplo de retorno em JSON:

    {
      "id": "a8ac430a-ea19-46cf-9617-ff8f47ef1260",
      "status": "available",
      "type": "Asset::Print",
      "created_at": "2017-06-13T11:59:47.686Z",
      "updated_at": "2017-06-13T11:59:48.787Z",
      "document": {
        "id": "d18abeb1-185e-4fa7-ba22-6b336d9c3ddd",
        "customer_id": "dacdf315-aff4-4710-84c5-09c272f1a841",
        "company_id": "b94888a8-ba9a-493a-8373-ccd0202784c6",
        "document_schema_id": "8479b00b-f06e-4f85-b9f5-98a240d1f90d",
        "created_at": "2017-06-13T11:59:44.518Z",
        "updated_at": "2017-06-13T11:59:47.607Z",
        "status": "success",
        "amount": 1985.52,
        "sequence": 126,
        "serie": "FASTN"
      }
    }

Retorna os dados do asset solicitado.

Parâmetro Descrição
:id

obrigatório

Id do asset criado

Baixando um asset

GET https://api.fastnotas.com/v1/assets/{ASSET_ID}/download

    curl -X GET https://api.fastnotas.com/v1/assets/{ASSET_ID}/download \
    -u 'YOUR_API_KEY:'

Retorna o asset em formato para impressão (se houver).

Parâmetro Descrição
:id

obrigatório

Id do asset criado

HTTP status codes

A API do Fast Notas segue o padrão que usa códigos de resposta HTTP convencionais para indicar o sucesso ou fracasso de uma solicitação da API. Em geral, os códigos na gama 2xx indicam sucesso, os códigos na gama 4xx indicam um erro dada a informação fornecida (por exemplo, um parâmetro necessário foi omitido, ou informado com um valor errado, etc) e os códigos na gama indicam um 5xx de erro com os servidores da lista (esses são raros).

HTTP Status:

Código Significado
200 - OK Request realizado com sucesso
201 - Created Cadastro criado com sucesso
204 - No Content Requisição sem conteúdo
400 - Bad Request Erro de sintaxe JSON no corpo do request
404 - Not Found Registro não encontrado
422 - Unprocessable Entity Parâmetros inválidos. Verificar erro na resposta
429 - Too Many Requests Limite de requisições excedido
500 - Internal Server Error Erro interno do servidor

Health Check

A fim de manter a transparência com seus clientes o Fast Notas disponibiliza um link com todos os dados de uptime da plataforma.

Abaixo segue alguns dados sobre o status atual da plataforma:

Uptime

alt text

Average Response Time

alt text