APIs Bulk-Data

APIs Bulk-Data são ofertadas apenas no pacote Ultimate e tem um funcionamento diferente das APIs RESTful.

As APIs Bulk-data tem por finalidade a extração de dados em massa do Sienge, de forma contínua e sem nenhuma paginação.

Devido à esse comportamento e visando a segurança da infraestrutura do Sienge, o recurso de APIs Bulk-data possuí um mecanismo limitador de requisições:

• (rate-limiting) -> Limite Máximo de 20 por minuto.

Por esse motivo recomenda-se analisar com muita atenção os filtros repassados no momento da requisição na API, afim de garantir todos os dados necessários logo na primeira requisição.

As APIs Bulk-data do Sienge, podem ser consumidas de forma Síncrona ou Assíncrona. Segue uma breve descrição de cada um dos modelos:

Requisição síncrona:

Retorna todos os dados imediatamente em stream em formato JSON na resposta da requisição.

    Exemplo: https://api.sienge.com.br/{{subdomain}}/public/api/bulk-data/v1/customer-extract-history?startDueDate=2019-01-01&endDueDate=2019-01-02

    Formato JSON de resposta: { "data": [ {..}, {..} ] }
    

Requisição assíncrona:

Ao informar parâmetro "_async=true", a requisição passa a ser tratada como assíncrona, sendo assim você irá receber na reposta um identificador da requisição, para que possa acompanhar o andamento da mesma e em seguida obter o resultado.

Quando utilizado o parâmetro "_async=true", você pode combinar com o parâmetro "_asyncChunkMaxSize" informando, em kilobytes, o tamanho máximo de cada chunk. Se não for informado, será tratado com um único chunk, também existem mais dois parametros para uso de webhooks, que são os parametros "_asyncWebHookUrl" "_asyncWebHookToken", após a tarefa ser finalizada esses 2 parametros são usado para dar um POST na URL informada.

    Exemplo: https://api.sienge.com.br/{{subdomain}}/public/api/bulk-data/v1/customer-extract-history?_async=true&_asyncChunkMaxSize=4096&startDueDate=2019-01-01&endDueDate=2019-01-02&_asyncWebHookUrl=minhaurl.com/webhook
    

    Formato do JSON de resposta: { "identifier": "5df56664915c3291f546db42" }
    

Consultando o status de uma requisição assíncrona:

Endpoint utilizado para acompanhar o andamento do processamento assíncrono de uma requisição.

    https://api.sienge.com.br/{tenant}/public/api/bulk-data/v1/async/{identifier}
    

    Exemplo: https://api.sienge.com.br/cury2/public/api/bulk-data/v1/async/5df56664915c3291f546db42
    

    Formato do JSON de resposta, quando:
    a requisição estiver aguardando para ser processada:
        { "status": "Waiting" }
    a requisição estiver sendo processada:
        { "status": "Processing" }
    o processamento da requisição tiver sido finalizado:
        { "status": "Finished", "chunks":5 }
    A propriedade "chunks" informa a quantidade de chunks gerados conforme o tamanho máximo definido no parâmetro "_asyncChunkMaxSize"; houver algum erro durante o processamento da requisição:
        { "status": "Failed", "error": "..." }
    

Obtendo o resultado de uma requisição assíncrona:

Endpoint utilizado para obter o conteúdo após o processamento assíncrono de uma requisição.

    https://api.sienge.com.br/{tenant}/public/api/bulk-data/v1/async/{identifier}/result/{chunk}
    

O parâmetro "{chunk}" é número do chunk que deseja obter o resultado. Por exemplo, se o total de chunks gerados for 5, você irá chamar 5 vezes o endpoint passando os valores 1, 2, 3, 4 e 5 (independente de ordem).

    Exemplo: https://api.sienge.com.br/cury2/public/api/bulk-data/v1/async/5df56664915c3291f546db42/result/1
    

    Formato do JSON de resposta: { "data": [ {..}, {..} ] }
    

---

A retenção dos resultados, atualmente está configurado para 24 horas.