Desenvolvedores

Introdução

A API da binds.co permite integrar seu sistema para disparar pesquisas e consultar resultados. Todas as requisições e respostas usam JSON em UTF-8.

Dica

Recomendamos usar o Postman para testar chamadas rapidamente.

Autenticação

A autenticação é feita via HTTP Basic Auth em todas as requisições.

Crie uma conta em adminv2.binds.co.
Valide seu e-mail.
Copie o token e a chave da API no painel da conta.
Gere o header Authorization: Basic <base64(token:chave)>.

Credenciais

Parâmetro	Onde	Tipo	Obrig.	Descrição
`token`	credencial	string	Sim	Identificador da conta (usuário/token de API).
`chave`	credencial	string	Sim	Chave secreta pareada ao token.
`Authorization`	header	string	Sim	Valor `Basic` seguido de `base64(token:chave)` em UTF-8.

Convenções da API

Regras comuns a todos os endpoints. Use esta seção como referência rápida de formato e comportamento.

Formato

Item	Descrição
`Content-Type`	Envie e espere `application/json; charset=utf-8`.
`Encoding`	Corpo e respostas em JSON com encoding UTF-8.
`Base URL`	Todas as rotas partem de `https://app.binds.co/api`.

Datas e paginação

Item	Descrição
`ISO8601`	Ex.: `2025-01-31T23:59:59.000Z` (UTC/GMT).
`Timezone`	Também aceito, ex.: `2025-01-31 20:59:59 -03:00`.
`skip / limit`	Inteiros para paginar listagens (`skip` padrão `0`).

Códigos HTTP

Código	Descrição
`2xx`	Requisição processada com sucesso.
`401`	Credenciais ausentes ou inválidas.
`4xx`	Erro no payload, parâmetro ou permissão — corrija antes de reenviar.
`5xx`	Erro temporário no servidor — aplique retry com backoff.

Exemplos por linguagem (mais usados)

Abaixo estão exemplos de envio via POST /seeds. Você só precisa trocar BINDS_TOKEN, BINDS_KEY, o collector e o canal em defaultSendingType.

Importante

Como o Basic Auth é secreto, faça chamadas da API preferencialmente no backend (server-to-server), e não no navegador.

JavaScript (Node 18+ com fetch)

const token = process.env.BINDS_TOKEN;
const key = process.env.BINDS_KEY;
const auth = Buffer.from(`${token}:${key}`).toString("base64");

const payload = {
  collector: "<collector_id>",
  defaultSendingType: "email",
  from: { name: "Cliente Exemplo", email: "cliente@empresa.com" },
  metadata: {
    codLoja: "667",
    codPedido: "PED-10393",
    telCliente: "+5511999999999",
    nomeVendedor: "João Silva"
  }
};

const res = await fetch("https://app.binds.co/api/seeds", {
  method: "POST",
  headers: {
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": `Basic ${auth}`
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error(`HTTP ${res.status} - ${await res.text()}`);
console.log(await res.json());

Python (requests)

import os, base64, requests

token = os.environ["BINDS_TOKEN"]
key = os.environ["BINDS_KEY"]
auth = base64.b64encode(f"{token}:{key}".encode("utf-8")).decode("utf-8")

payload = {
  "collector": "<collector_id>",
  "defaultSendingType": "email",
  "from": {"name": "Cliente Exemplo", "email": "cliente@empresa.com"},
  "metadata": {
    "codLoja": "667",
    "codPedido": "PED-10393",
    "telCliente": "+5511999999999",
    "nomeVendedor": "João Silva"
  }
}

res = requests.post(
  "https://app.binds.co/api/seeds",
  json=payload,
  headers={
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": f"Basic {auth}"
  },
  timeout=30
)
res.raise_for_status()
print(res.json())

PHP (cURL)

<?php
$token = getenv("BINDS_TOKEN");
$key = getenv("BINDS_KEY");
$auth = base64_encode($token . ":" . $key);

$payload = [
  "collector" => "<collector_id>",
  "defaultSendingType" => "email",
  "from" => ["name" => "Cliente Exemplo", "email" => "cliente@empresa.com"],
  "metadata" => [
    "codLoja" => "667",
    "codPedido" => "PED-10393",
    "telCliente" => "+5511999999999",
    "nomeVendedor" => "João Silva",
  ],
];

$ch = curl_init("https://app.binds.co/api/seeds");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json; charset=utf-8",
    "Authorization: Basic " . $auth,
  ],
  CURLOPT_POSTFIELDS => json_encode($payload),
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($body === false) throw new Exception(curl_error($ch));
curl_close($ch);

if ($status < 200 || $status >= 300) throw new Exception("HTTP " . $status . " - " . $body);
echo $body;

Java (Java 11+ HttpClient)

import java.net.URI;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class BindsSeeds {
  public static void main(String[] args) throws Exception {
    String token = System.getenv("BINDS_TOKEN");
    String key = System.getenv("BINDS_KEY");
    String auth = Base64.getEncoder().encodeToString((token + ":" + key).getBytes(StandardCharsets.UTF_8));

    String json = """
    {
      "collector": "<collector_id>",
      "defaultSendingType": "email",
      "from": { "name": "Cliente Exemplo", "email": "cliente@empresa.com" },
      "metadata": {
        "codLoja": "667",
        "codPedido": "PED-10393",
        "telCliente": "+5511999999999",
        "nomeVendedor": "João Silva"
      }
    }
    """;

    HttpClient client = HttpClient.newHttpClient();
    HttpRequest req = HttpRequest.newBuilder()
      .uri(URI.create("https://app.binds.co/api/seeds"))
      .header("Content-Type", "application/json; charset=utf-8")
      .header("Authorization", "Basic " + auth)
      .POST(HttpRequest.BodyPublishers.ofString(json))
      .build();

    HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
    if (res.statusCode() < 200 || res.statusCode() >= 300) {
      throw new RuntimeException("HTTP " + res.statusCode() + " - " + res.body());
    }
    System.out.println(res.body());
  }
}

C# (.NET / HttpClient)

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;

var token = Environment.GetEnvironmentVariable("BINDS_TOKEN");
var key = Environment.GetEnvironmentVariable("BINDS_KEY");
var auth = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{token}:{key}"));

var payload = new {
  collector = "<collector_id>",
  defaultSendingType = "email",
  from = new { name = "Cliente Exemplo", email = "cliente@empresa.com" },
  metadata = new {
    codLoja = "667",
    codPedido = "PED-10393",
    telCliente = "+5511999999999",
    nomeVendedor = "João Silva"
  }
};

using var http = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Post, "https://app.binds.co/api/seeds");
req.Headers.TryAddWithoutValidation("Authorization", $"Basic {auth}");
req.Content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");

var res = await http.SendAsync(req);
var body = await res.Content.ReadAsStringAsync();
if (!res.IsSuccessStatusCode) throw new Exception($"HTTP {(int)res.StatusCode} - {body}");
Console.WriteLine(body);

Go (net/http)

package main

import (
  "bytes"
  "encoding/base64"
  "fmt"
  "net/http"
  "os"
)

func main() {
  token := os.Getenv("BINDS_TOKEN")
  key := os.Getenv("BINDS_KEY")
  auth := base64.StdEncoding.EncodeToString([]byte(token + ":" + key))

  body := []byte(`{
    "collector":"<collector_id>",
    "defaultSendingType":"email",
    "from":{"name":"Cliente Exemplo","email":"cliente@empresa.com"},
    "metadata":{
      "codLoja":"667",
      "codPedido":"PED-10393",
      "telCliente":"+5511999999999",
      "nomeVendedor":"João Silva"
    }
  }`)

  req, _ := http.NewRequest("POST", "https://app.binds.co/api/seeds", bytes.NewReader(body))
  req.Header.Set("Content-Type", "application/json; charset=utf-8")
  req.Header.Set("Authorization", "Basic "+auth)

  res, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer res.Body.Close()

  if res.StatusCode < 200 || res.StatusCode >= 300 {
    fmt.Println("HTTP", res.StatusCode)
  }
  // leia o body conforme necessário (io.ReadAll)
}

Ruby (Net::HTTP)

require "net/http"
require "uri"
require "json"
require "base64"

token = ENV["BINDS_TOKEN"]
key = ENV["BINDS_KEY"]
auth = Base64.strict_encode64("#{token}:#{key}")

uri = URI("https://app.binds.co/api/seeds")
req = Net::HTTP::Post.new(uri)
req["Content-Type"] = "application/json; charset=utf-8"
req["Authorization"] = "Basic #{auth}"
req.body = {
  collector: "<collector_id>",
  defaultSendingType: "email",
  from: { name: "Cliente Exemplo", email: "cliente@empresa.com" },
  metadata: {
    codLoja: "667",
    codPedido: "PED-10393",
    telCliente: "+5511999999999",
    nomeVendedor: "João Silva"
  }
}.to_json

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
raise "HTTP #{res.code} - #{res.body}" unless res.code.to_i.between?(200, 299)
puts res.body

cURL (bash)

curl -X POST \
  "https://app.binds.co/api/seeds" \
  -H "Authorization: Basic <base64(token:chave)>" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "collector":"<collector_id>",
    "defaultSendingType":"email",
    "from":{"name":"Cliente Exemplo","email":"cliente@empresa.com"},
    "metadata":{
      "codLoja":"667",
      "codPedido":"PED-10393",
      "telCliente":"+5511999999999",
      "nomeVendedor":"João Silva"
    }
  }'

Listar pesquisas

Consulta as informações e detalhes de uma lista de pesquisas criadas.

GET /surveys

Parâmetros

Parâmetro	Onde	Tipo	Obrig.	Descrição
`Authorization`	header	string	Sim	`Basic <base64(token:chave)>`
`Content-Type`	header	string	Não	Recomendado: `application/json; charset=utf-8`.

Este endpoint não possui parâmetros de path ou query string.

Resposta 200 OK

Campo	Tipo	Descrição
`(array)`	array	Lista de pesquisas da conta.
`_id`	string	Identificador da pesquisa (use em `/surveys/{surveyId}/responses`).
`name`	string	Nome/título da pesquisa.
`status`	string	Estado da pesquisa (ex.: ativa, rascunho).

Exemplo (curl)

curl -X GET \
  "https://app.binds.co/api/surveys" \
  -H "Authorization: Basic <base64(token:chave)>" \
  -H "Content-Type: application/json"

JavaScript (Node 18+ com fetch)

const token = process.env.BINDS_TOKEN;
const key = process.env.BINDS_KEY;
const auth = Buffer.from(`${token}:${key}`).toString("base64");

const res = await fetch("https://app.binds.co/api/surveys", {
  method: "GET",
  headers: {
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": `Basic ${auth}`
  }
});

if (!res.ok) throw new Error(`HTTP ${res.status} - ${await res.text()}`);
console.log(await res.json());

Python (requests)

import os, base64, requests

token = os.environ["BINDS_TOKEN"]
key = os.environ["BINDS_KEY"]
auth = base64.b64encode(f"{token}:{key}".encode("utf-8")).decode("utf-8")

res = requests.get(
  "https://app.binds.co/api/surveys",
  headers={
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": f"Basic {auth}"
  },
  timeout=30
)
res.raise_for_status()
print(res.json())

PHP (cURL)

<?php
$token = getenv("BINDS_TOKEN");
$key = getenv("BINDS_KEY");
$auth = base64_encode($token . ":" . $key);

$ch = curl_init("https://app.binds.co/api/surveys");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json; charset=utf-8",
    "Authorization: Basic " . $auth,
  ],
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($body === false) throw new Exception(curl_error($ch));
curl_close($ch);

if ($status < 200 || $status >= 300) throw new Exception("HTTP " . $status . " - " . $body);
echo $body;

Java (Java 11+ HttpClient)

import java.net.URI;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class BindsSurveys {
  public static void main(String[] args) throws Exception {
    String token = System.getenv("BINDS_TOKEN");
    String key = System.getenv("BINDS_KEY");
    String auth = Base64.getEncoder().encodeToString((token + ":" + key).getBytes(StandardCharsets.UTF_8));

    HttpClient client = HttpClient.newHttpClient();
    HttpRequest req = HttpRequest.newBuilder()
      .uri(URI.create("https://app.binds.co/api/surveys"))
      .header("Content-Type", "application/json; charset=utf-8")
      .header("Authorization", "Basic " + auth)
      .GET()
      .build();

    HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
    if (res.statusCode() < 200 || res.statusCode() >= 300) {
      throw new RuntimeException("HTTP " + res.statusCode() + " - " + res.body());
    }
    System.out.println(res.body());
  }
}

C# (.NET / HttpClient)

using System;
using System.Net.Http;
using System.Text;

var token = Environment.GetEnvironmentVariable("BINDS_TOKEN");
var key = Environment.GetEnvironmentVariable("BINDS_KEY");
var auth = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{token}:{key}"));

using var http = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Get, "https://app.binds.co/api/surveys");
req.Headers.TryAddWithoutValidation("Authorization", $"Basic {auth}");
req.Headers.TryAddWithoutValidation("Content-Type", "application/json; charset=utf-8");

var res = await http.SendAsync(req);
var body = await res.Content.ReadAsStringAsync();
if (!res.IsSuccessStatusCode) throw new Exception($"HTTP {(int)res.StatusCode} - {body}");
Console.WriteLine(body);

Go (net/http)

package main

import (
  "encoding/base64"
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  token := os.Getenv("BINDS_TOKEN")
  key := os.Getenv("BINDS_KEY")
  auth := base64.StdEncoding.EncodeToString([]byte(token + ":" + key))

  req, _ := http.NewRequest("GET", "https://app.binds.co/api/surveys", nil)
  req.Header.Set("Content-Type", "application/json; charset=utf-8")
  req.Header.Set("Authorization", "Basic "+auth)

  res, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer res.Body.Close()

  b, _ := io.ReadAll(res.Body)
  if res.StatusCode < 200 || res.StatusCode >= 300 {
    panic(fmt.Sprintf("HTTP %d - %s", res.StatusCode, string(b)))
  }
  fmt.Println(string(b))
}

Ruby (Net::HTTP)

require "net/http"
require "uri"
require "base64"

token = ENV["BINDS_TOKEN"]
key = ENV["BINDS_KEY"]
auth = Base64.strict_encode64("#{token}:#{key}")

uri = URI("https://app.binds.co/api/surveys")
req = Net::HTTP::Get.new(uri)
req["Content-Type"] = "application/json; charset=utf-8"
req["Authorization"] = "Basic #{auth}"

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
raise "HTTP #{res.code} - #{res.body}" unless res.code.to_i.between?(200, 299)
puts res.body

cURL (bash)

curl -X GET \
  "https://app.binds.co/api/surveys" \
  -H "Authorization: Basic <base64(token:chave)>" \
  -H "Content-Type: application/json; charset=utf-8"

Listar coletores

Obtém collectors (chaves) usados no envio de pesquisas.

GET /collectors

Parâmetros

Parâmetro	Onde	Tipo	Obrig.	Descrição
`Authorization`	header	string	Sim	`Basic <base64(token:chave)>`
`Content-Type`	header	string	Não	Recomendado: `application/json; charset=utf-8`.

Sem parâmetros de path ou query string.

Resposta 200 OK

Campo	Tipo	Descrição
`(array)`	array	Lista de coletores disponíveis para envio.
`_id`	string	ID do coletor; use no campo `collector` do `POST /seeds`.
`name`	string	Nome descritivo do coletor/canal.
`survey`	string	Pesquisa vinculada ao coletor.

JavaScript (Node 18+ com fetch)

const token = process.env.BINDS_TOKEN;
const key = process.env.BINDS_KEY;
const auth = Buffer.from(`${token}:${key}`).toString("base64");

const res = await fetch("https://app.binds.co/api/collectors", {
  method: "GET",
  headers: {
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": `Basic ${auth}`
  }
});

if (!res.ok) throw new Error(`HTTP ${res.status} - ${await res.text()}`);
console.log(await res.json());

Python (requests)

import os, base64, requests

token = os.environ["BINDS_TOKEN"]
key = os.environ["BINDS_KEY"]
auth = base64.b64encode(f"{token}:{key}".encode("utf-8")).decode("utf-8")

res = requests.get(
  "https://app.binds.co/api/collectors",
  headers={
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": f"Basic {auth}"
  },
  timeout=30
)
res.raise_for_status()
print(res.json())

PHP (cURL)

<?php
$token = getenv("BINDS_TOKEN");
$key = getenv("BINDS_KEY");
$auth = base64_encode($token . ":" . $key);

$ch = curl_init("https://app.binds.co/api/collectors");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json; charset=utf-8",
    "Authorization: Basic " . $auth,
  ],
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($body === false) throw new Exception(curl_error($ch));
curl_close($ch);

if ($status < 200 || $status >= 300) throw new Exception("HTTP " . $status . " - " . $body);
echo $body;

Java (Java 11+ HttpClient)

import java.net.URI;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class BindsCollectors {
  public static void main(String[] args) throws Exception {
    String token = System.getenv("BINDS_TOKEN");
    String key = System.getenv("BINDS_KEY");
    String auth = Base64.getEncoder().encodeToString((token + ":" + key).getBytes(StandardCharsets.UTF_8));

    HttpClient client = HttpClient.newHttpClient();
    HttpRequest req = HttpRequest.newBuilder()
      .uri(URI.create("https://app.binds.co/api/collectors"))
      .header("Content-Type", "application/json; charset=utf-8")
      .header("Authorization", "Basic " + auth)
      .GET()
      .build();

    HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
    if (res.statusCode() < 200 || res.statusCode() >= 300) {
      throw new RuntimeException("HTTP " + res.statusCode() + " - " + res.body());
    }
    System.out.println(res.body());
  }
}

C# (.NET / HttpClient)

using System;
using System.Net.Http;
using System.Text;

var token = Environment.GetEnvironmentVariable("BINDS_TOKEN");
var key = Environment.GetEnvironmentVariable("BINDS_KEY");
var auth = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{token}:{key}"));

using var http = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Get, "https://app.binds.co/api/collectors");
req.Headers.TryAddWithoutValidation("Authorization", $"Basic {auth}");
req.Headers.TryAddWithoutValidation("Content-Type", "application/json; charset=utf-8");

var res = await http.SendAsync(req);
var body = await res.Content.ReadAsStringAsync();
if (!res.IsSuccessStatusCode) throw new Exception($"HTTP {(int)res.StatusCode} - {body}");
Console.WriteLine(body);

Go (net/http)

package main

import (
  "encoding/base64"
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  token := os.Getenv("BINDS_TOKEN")
  key := os.Getenv("BINDS_KEY")
  auth := base64.StdEncoding.EncodeToString([]byte(token + ":" + key))

  req, _ := http.NewRequest("GET", "https://app.binds.co/api/collectors", nil)
  req.Header.Set("Content-Type", "application/json; charset=utf-8")
  req.Header.Set("Authorization", "Basic "+auth)

  res, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer res.Body.Close()

  b, _ := io.ReadAll(res.Body)
  if res.StatusCode < 200 || res.StatusCode >= 300 {
    panic(fmt.Sprintf("HTTP %d - %s", res.StatusCode, string(b)))
  }
  fmt.Println(string(b))
}

Ruby (Net::HTTP)

require "net/http"
require "uri"
require "base64"

token = ENV["BINDS_TOKEN"]
key = ENV["BINDS_KEY"]
auth = Base64.strict_encode64("#{token}:#{key}")

uri = URI("https://app.binds.co/api/collectors")
req = Net::HTTP::Get.new(uri)
req["Content-Type"] = "application/json; charset=utf-8"
req["Authorization"] = "Basic #{auth}"

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
raise "HTTP #{res.code} - #{res.body}" unless res.code.to_i.between?(200, 299)
puts res.body

cURL (bash)

curl -X GET \
  "https://app.binds.co/api/collectors" \
  -H "Authorization: Basic <base64(token:chave)>" \
  -H "Content-Type: application/json; charset=utf-8"

Enviar pesquisa (seed)

Dispare uma pesquisa via API notificando a binds.co quando um evento ocorrer (ex.: compra, entrega). O campo collector é obrigatório. Use defaultSendingType para definir o canal de envio (email, sms ou whatsApp).

POST /seeds

Parâmetros (body JSON)

Parâmetro	Onde	Tipo	Obrig.	Descrição
`collector`	body	string	Sim	ID do coletor obtido em `GET /collectors`.
`defaultSendingType`	body	string	Não	Canal de envio da pesquisa: `email`, `sms` ou `whatsApp`.
`from`	body	object	Sim	Dados do respondente que receberá a pesquisa.
`from.name`	body	string	Sim	Nome do contato.
`from.email`	body	string	Cond.	E-mail válido. Obrigatório se `from.phone` não for enviado.
`from.phone`	body	string	Não	Telefone em formato internacional, ex.: `+5511999999999`.
`metadata`	body	object	Não	Pares chave/valor livres para enriquecer relatórios e filtros.

Resposta

Status	Descrição
`201 Created`	Evento recebido e pesquisa enfileirada para envio.
`4xx`	Payload inválido, coletor inexistente ou credencial incorreta.
`Corpo`	JSON com dados do seed criado (inclui identificador interno do envio).

Body (exemplo)

{
  "collector": "<collector_id>",
  "defaultSendingType": "email",
  "from": {
    "name": "Cliente Exemplo",
    "email": "cliente@empresa.com"
  },
  "metadata": {
    "codLoja": "667",
    "codPedido": "PED-10393",
    "telCliente": "+5511999999999",
    "nomeVendedor": "João Silva"
  }
}

JavaScript (Node 18+ com fetch)

const token = process.env.BINDS_TOKEN;
const key = process.env.BINDS_KEY;
const auth = Buffer.from(`${token}:${key}`).toString("base64");

const payload = {
  collector: "<collector_id>",
  defaultSendingType: "email",
  from: { name: "Cliente Exemplo", email: "cliente@empresa.com" },
  metadata: {
    codLoja: "667",
    codPedido: "PED-10393",
    telCliente: "+5511999999999",
    nomeVendedor: "João Silva"
  }
};

const res = await fetch("https://app.binds.co/api/seeds", {
  method: "POST",
  headers: {
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": `Basic ${auth}`
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error(`HTTP ${res.status} - ${await res.text()}`);
console.log(await res.json());

Python (requests)

import os, base64, requests

token = os.environ["BINDS_TOKEN"]
key = os.environ["BINDS_KEY"]
auth = base64.b64encode(f"{token}:{key}".encode("utf-8")).decode("utf-8")

payload = {
  "collector": "<collector_id>",
  "defaultSendingType": "email",
  "from": {"name": "Cliente Exemplo", "email": "cliente@empresa.com"},
  "metadata": {
    "codLoja": "667",
    "codPedido": "PED-10393",
    "telCliente": "+5511999999999",
    "nomeVendedor": "João Silva"
  }
}

res = requests.post(
  "https://app.binds.co/api/seeds",
  json=payload,
  headers={
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": f"Basic {auth}"
  },
  timeout=30
)
res.raise_for_status()
print(res.json())

PHP (cURL)

<?php
$token = getenv("BINDS_TOKEN");
$key = getenv("BINDS_KEY");
$auth = base64_encode($token . ":" . $key);

$payload = [
  "collector" => "<collector_id>",
  "defaultSendingType" => "email",
  "from" => ["name" => "Cliente Exemplo", "email" => "cliente@empresa.com"],
  "metadata" => [
    "codLoja" => "667",
    "codPedido" => "PED-10393",
    "telCliente" => "+5511999999999",
    "nomeVendedor" => "João Silva",
  ],
];

$ch = curl_init("https://app.binds.co/api/seeds");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json; charset=utf-8",
    "Authorization: Basic " . $auth,
  ],
  CURLOPT_POSTFIELDS => json_encode($payload),
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($body === false) throw new Exception(curl_error($ch));
curl_close($ch);

if ($status < 200 || $status >= 300) throw new Exception("HTTP " . $status . " - " . $body);
echo $body;

Java (Java 11+ HttpClient)

import java.net.URI;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class BindsSeeds {
  public static void main(String[] args) throws Exception {
    String token = System.getenv("BINDS_TOKEN");
    String key = System.getenv("BINDS_KEY");
    String auth = Base64.getEncoder().encodeToString((token + ":" + key).getBytes(StandardCharsets.UTF_8));

    String json = """
    {
      "collector": "<collector_id>",
      "defaultSendingType": "email",
      "from": { "name": "Cliente Exemplo", "email": "cliente@empresa.com" },
      "metadata": {
        "codLoja": "667",
        "codPedido": "PED-10393",
        "telCliente": "+5511999999999",
        "nomeVendedor": "João Silva"
      }
    }
    """;

    HttpClient client = HttpClient.newHttpClient();
    HttpRequest req = HttpRequest.newBuilder()
      .uri(URI.create("https://app.binds.co/api/seeds"))
      .header("Content-Type", "application/json; charset=utf-8")
      .header("Authorization", "Basic " + auth)
      .POST(HttpRequest.BodyPublishers.ofString(json))
      .build();

    HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
    if (res.statusCode() < 200 || res.statusCode() >= 300) {
      throw new RuntimeException("HTTP " + res.statusCode() + " - " + res.body());
    }
    System.out.println(res.body());
  }
}

C# (.NET / HttpClient)

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;

var token = Environment.GetEnvironmentVariable("BINDS_TOKEN");
var key = Environment.GetEnvironmentVariable("BINDS_KEY");
var auth = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{token}:{key}"));

var payload = new {
  collector = "<collector_id>",
  defaultSendingType = "email",
  from = new { name = "Cliente Exemplo", email = "cliente@empresa.com" },
  metadata = new {
    codLoja = "667",
    codPedido = "PED-10393",
    telCliente = "+5511999999999",
    nomeVendedor = "João Silva"
  }
};

using var http = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Post, "https://app.binds.co/api/seeds");
req.Headers.TryAddWithoutValidation("Authorization", $"Basic {auth}");
req.Content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");

var res = await http.SendAsync(req);
var body = await res.Content.ReadAsStringAsync();
if (!res.IsSuccessStatusCode) throw new Exception($"HTTP {(int)res.StatusCode} - {body}");
Console.WriteLine(body);

Go (net/http)

package main

import (
  "bytes"
  "encoding/base64"
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  token := os.Getenv("BINDS_TOKEN")
  key := os.Getenv("BINDS_KEY")
  auth := base64.StdEncoding.EncodeToString([]byte(token + ":" + key))

  body := []byte(`{
    "collector":"<collector_id>",
    "defaultSendingType":"email",
    "from":{"name":"Cliente Exemplo","email":"cliente@empresa.com"},
    "metadata":{
      "codLoja":"667",
      "codPedido":"PED-10393",
      "telCliente":"+5511999999999",
      "nomeVendedor":"João Silva"
    }
  }`)

  req, _ := http.NewRequest("POST", "https://app.binds.co/api/seeds", bytes.NewReader(body))
  req.Header.Set("Content-Type", "application/json; charset=utf-8")
  req.Header.Set("Authorization", "Basic "+auth)

  res, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer res.Body.Close()

  b, _ := io.ReadAll(res.Body)
  if res.StatusCode < 200 || res.StatusCode >= 300 {
    panic(fmt.Sprintf("HTTP %d - %s", res.StatusCode, string(b)))
  }
  fmt.Println(string(b))
}

Ruby (Net::HTTP)

require "net/http"
require "uri"
require "json"
require "base64"

token = ENV["BINDS_TOKEN"]
key = ENV["BINDS_KEY"]
auth = Base64.strict_encode64("#{token}:#{key}")

uri = URI("https://app.binds.co/api/seeds")
req = Net::HTTP::Post.new(uri)
req["Content-Type"] = "application/json; charset=utf-8"
req["Authorization"] = "Basic #{auth}"
req.body = {
  collector: "<collector_id>",
  defaultSendingType: "email",
  from: { name: "Cliente Exemplo", email: "cliente@empresa.com" },
  metadata: {
    codLoja: "667",
    codPedido: "PED-10393",
    telCliente: "+5511999999999",
    nomeVendedor: "João Silva"
  }
}.to_json

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
raise "HTTP #{res.code} - #{res.body}" unless res.code.to_i.between?(200, 299)
puts res.body

cURL (bash)

curl -X POST \
  "https://app.binds.co/api/seeds" \
  -H "Authorization: Basic <base64(token:chave)>" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "collector":"<collector_id>",
    "defaultSendingType":"email",
    "from":{"name":"Cliente Exemplo","email":"cliente@empresa.com"},
    "metadata":{
      "codLoja":"667",
      "codPedido":"PED-10393",
      "telCliente":"+5511999999999",
      "nomeVendedor":"João Silva"
    }
  }'

Listar respostas

Consulta respostas de uma pesquisa específica.

GET /surveys/{surveyId}/responses

Parâmetros

Parâmetro	Onde	Tipo	Obrig.	Descrição
`Authorization`	header	string	Sim	`Basic <base64(token:chave)>`
`surveyId`	path	string	Sim	ID da pesquisa (`_id` retornado por `GET /surveys`).
`startDate`	query	string	Não	Início do intervalo (ISO8601).
`endDate`	query	string	Não	Fim do intervalo (ISO8601).
`skip`	query	integer	Não	Registros a pular; padrão `0`.
`limit`	query	integer	Não	Máximo de registros por página; ex.: `1000`.

Resposta 200 OK

Campo	Tipo	Descrição
`(array)`	array	Lista de respostas da pesquisa no período informado.
`response_id`	string	Identificador único da resposta (use como chave de idempotência).
`survey_id`	string	Pesquisa de origem.
`response_at`	string	Data/hora da resposta (ISO8601).
`score`	number	Nota/indicador principal (NPS, CSAT etc.).
`comment`	string	Comentário textual, quando houver.
`metadata`	object	Campos customizados enviados no seed ou coletados na resposta.

Filtro por período

Combine startDate e endDate para sincronizações incrementais (ETL, planilhas, BI). Use skip e limit para paginar resultados grandes.

curl -X GET \
  "https://app.binds.co/api/surveys/<surveyId>/responses?startDate=2025-01-01T00:00:00.000Z&endDate=2025-01-31T23:59:59.000Z&skip=0&limit=1000" \
  -H "Authorization: Basic <base64(token:chave)>"

JavaScript (Node 18+ com fetch)

const token = process.env.BINDS_TOKEN;
const key = process.env.BINDS_KEY;
const auth = Buffer.from(`${token}:${key}`).toString("base64");

const surveyId = "<surveyId>";
const qs = new URLSearchParams({
  startDate: "2025-01-01T00:00:00.000Z",
  endDate: "2025-01-31T23:59:59.000Z",
  skip: "0",
  limit: "1000"
});

const url = `https://app.binds.co/api/surveys/${encodeURIComponent(surveyId)}/responses?${qs}`;
const res = await fetch(url, { headers: { "Authorization": `Basic ${auth}` } });
if (!res.ok) throw new Error(`HTTP ${res.status} - ${await res.text()}`);
console.log(await res.json());

Python (requests)

import os, base64, requests

token = os.environ["BINDS_TOKEN"]
key = os.environ["BINDS_KEY"]
auth = base64.b64encode(f"{token}:{key}".encode("utf-8")).decode("utf-8")

survey_id = "<surveyId>"
params = {
  "startDate": "2025-01-01T00:00:00.000Z",
  "endDate": "2025-01-31T23:59:59.000Z",
  "skip": 0,
  "limit": 1000
}

res = requests.get(
  f"https://app.binds.co/api/surveys/{survey_id}/responses",
  params=params,
  headers={"Authorization": f"Basic {auth}"},
  timeout=30
)
res.raise_for_status()
print(res.json())

PHP (cURL)

<?php
$token = getenv("BINDS_TOKEN");
$key = getenv("BINDS_KEY");
$auth = base64_encode($token . ":" . $key);

$surveyId = "<surveyId>";
$qs = http_build_query([
  "startDate" => "2025-01-01T00:00:00.000Z",
  "endDate" => "2025-01-31T23:59:59.000Z",
  "skip" => 0,
  "limit" => 1000,
]);

$url = "https://app.binds.co/api/surveys/" . rawurlencode($surveyId) . "/responses?" . $qs;
$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Basic " . $auth],
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($body === false) throw new Exception(curl_error($ch));
curl_close($ch);

if ($status < 200 || $status >= 300) throw new Exception("HTTP " . $status . " - " . $body);
echo $body;

Java (Java 11+ HttpClient)

import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class BindsResponses {
  public static void main(String[] args) throws Exception {
    String token = System.getenv("BINDS_TOKEN");
    String key = System.getenv("BINDS_KEY");
    String auth = Base64.getEncoder().encodeToString((token + ":" + key).getBytes(StandardCharsets.UTF_8));

    String surveyId = "<surveyId>";
    String qs =
      "startDate=" + URLEncoder.encode("2025-01-01T00:00:00.000Z", StandardCharsets.UTF_8) +
      "&endDate=" + URLEncoder.encode("2025-01-31T23:59:59.000Z", StandardCharsets.UTF_8) +
      "&skip=0&limit=1000";

    URI uri = URI.create("https://app.binds.co/api/surveys/" + URLEncoder.encode(surveyId, StandardCharsets.UTF_8) + "/responses?" + qs);
    HttpClient client = HttpClient.newHttpClient();
    HttpRequest req = HttpRequest.newBuilder()
      .uri(uri)
      .header("Authorization", "Basic " + auth)
      .GET()
      .build();

    HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
    if (res.statusCode() < 200 || res.statusCode() >= 300) {
      throw new RuntimeException("HTTP " + res.statusCode() + " - " + res.body());
    }
    System.out.println(res.body());
  }
}

C# (.NET / HttpClient)

using System;
using System.Net.Http;
using System.Text;

var token = Environment.GetEnvironmentVariable("BINDS_TOKEN");
var key = Environment.GetEnvironmentVariable("BINDS_KEY");
var auth = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{token}:{key}"));

var surveyId = "<surveyId>";
var url = "https://app.binds.co/api/surveys/" + Uri.EscapeDataString(surveyId)
  + "/responses?startDate=" + Uri.EscapeDataString("2025-01-01T00:00:00.000Z")
  + "&endDate=" + Uri.EscapeDataString("2025-01-31T23:59:59.000Z")
  + "&skip=0&limit=1000";

using var http = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Get, url);
req.Headers.TryAddWithoutValidation("Authorization", $"Basic {auth}");

var res = await http.SendAsync(req);
var body = await res.Content.ReadAsStringAsync();
if (!res.IsSuccessStatusCode) throw new Exception($"HTTP {(int)res.StatusCode} - {body}");
Console.WriteLine(body);

Go (net/http)

package main

import (
  "encoding/base64"
  "fmt"
  "io"
  "net/http"
  "net/url"
  "os"
)

func main() {
  token := os.Getenv("BINDS_TOKEN")
  key := os.Getenv("BINDS_KEY")
  auth := base64.StdEncoding.EncodeToString([]byte(token + ":" + key))

  surveyId := "<surveyId>"
  qs := url.Values{}
  qs.Set("startDate", "2025-01-01T00:00:00.000Z")
  qs.Set("endDate", "2025-01-31T23:59:59.000Z")
  qs.Set("skip", "0")
  qs.Set("limit", "1000")

  u := "https://app.binds.co/api/surveys/" + url.PathEscape(surveyId) + "/responses?" + qs.Encode()
  req, _ := http.NewRequest("GET", u, nil)
  req.Header.Set("Authorization", "Basic "+auth)

  res, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer res.Body.Close()

  b, _ := io.ReadAll(res.Body)
  if res.StatusCode < 200 || res.StatusCode >= 300 {
    panic(fmt.Sprintf("HTTP %d - %s", res.StatusCode, string(b)))
  }
  fmt.Println(string(b))
}

Ruby (Net::HTTP)

require "net/http"
require "uri"
require "base64"

token = ENV["BINDS_TOKEN"]
key = ENV["BINDS_KEY"]
auth = Base64.strict_encode64("#{token}:#{key}")

survey_id = "<surveyId>"
uri = URI("https://app.binds.co/api/surveys/#{URI.encode_www_form_component(survey_id)}/responses")
uri.query = URI.encode_www_form(
  startDate: "2025-01-01T00:00:00.000Z",
  endDate: "2025-01-31T23:59:59.000Z",
  skip: 0,
  limit: 1000
)

req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Basic #{auth}"

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
raise "HTTP #{res.code} - #{res.body}" unless res.code.to_i.between?(200, 299)
puts res.body

cURL (bash)

curl -X GET \
  "https://app.binds.co/api/surveys/<surveyId>/responses?startDate=2025-01-01T00:00:00.000Z&endDate=2025-01-31T23:59:59.000Z&skip=0&limit=1000" \
  -H "Authorization: Basic <base64(token:chave)>"

Listar abordagens

Consulta envios (abordagens) de uma pesquisa.

GET /survey-sendings?survey={surveyId}

Parâmetros

Parâmetro	Onde	Tipo	Obrig.	Descrição
`Authorization`	header	string	Sim	`Basic <base64(token:chave)>`
`survey`	query	string	Sim	ID da pesquisa cujas abordagens/envios serão listados.

Resposta 200 OK

Campo	Tipo	Descrição
`(array)`	array	Lista de abordagens (envios) da pesquisa.
`_id`	string	Identificador da abordagem/envio.
`survey`	string	Pesquisa vinculada.
`from`	object	Contato abordado (`name`, `email`, `phone`).
`metadata`	object	Metadados enviados no seed.
`createdAt`	string	Data/hora do envio (ISO8601).
`status`	string	Estado do envio (ex.: enviado, respondido).

curl -X GET \
  "https://app.binds.co/api/survey-sendings?survey=<surveyId>" \
  -H "Authorization: Basic <base64(token:chave)>"

JavaScript (Node 18+ com fetch)

const token = process.env.BINDS_TOKEN;
const key = process.env.BINDS_KEY;
const auth = Buffer.from(`${token}:${key}`).toString("base64");

const surveyId = "<surveyId>";
const url = `https://app.binds.co/api/survey-sendings?survey=${encodeURIComponent(surveyId)}`;

const res = await fetch(url, { headers: { "Authorization": `Basic ${auth}` } });
if (!res.ok) throw new Error(`HTTP ${res.status} - ${await res.text()}`);
console.log(await res.json());

Python (requests)

import os, base64, requests

token = os.environ["BINDS_TOKEN"]
key = os.environ["BINDS_KEY"]
auth = base64.b64encode(f"{token}:{key}".encode("utf-8")).decode("utf-8")

survey_id = "<surveyId>"
res = requests.get(
  "https://app.binds.co/api/survey-sendings",
  params={"survey": survey_id},
  headers={"Authorization": f"Basic {auth}"},
  timeout=30
)
res.raise_for_status()
print(res.json())

PHP (cURL)

<?php
$token = getenv("BINDS_TOKEN");
$key = getenv("BINDS_KEY");
$auth = base64_encode($token . ":" . $key);

$surveyId = "<surveyId>";
$url = "https://app.binds.co/api/survey-sendings?survey=" . rawurlencode($surveyId);

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Basic " . $auth],
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($body === false) throw new Exception(curl_error($ch));
curl_close($ch);

if ($status < 200 || $status >= 300) throw new Exception("HTTP " . $status . " - " . $body);
echo $body;

Java (Java 11+ HttpClient)

import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class BindsSendings {
  public static void main(String[] args) throws Exception {
    String token = System.getenv("BINDS_TOKEN");
    String key = System.getenv("BINDS_KEY");
    String auth = Base64.getEncoder().encodeToString((token + ":" + key).getBytes(StandardCharsets.UTF_8));

    String surveyId = "<surveyId>";
    URI uri = URI.create("https://app.binds.co/api/survey-sendings?survey=" + URLEncoder.encode(surveyId, StandardCharsets.UTF_8));

    HttpClient client = HttpClient.newHttpClient();
    HttpRequest req = HttpRequest.newBuilder()
      .uri(uri)
      .header("Authorization", "Basic " + auth)
      .GET()
      .build();

    HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
    if (res.statusCode() < 200 || res.statusCode() >= 300) {
      throw new RuntimeException("HTTP " + res.statusCode() + " - " + res.body());
    }
    System.out.println(res.body());
  }
}

C# (.NET / HttpClient)

using System;
using System.Net.Http;
using System.Text;

var token = Environment.GetEnvironmentVariable("BINDS_TOKEN");
var key = Environment.GetEnvironmentVariable("BINDS_KEY");
var auth = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{token}:{key}"));

var surveyId = "<surveyId>";
var url = "https://app.binds.co/api/survey-sendings?survey=" + Uri.EscapeDataString(surveyId);

using var http = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Get, url);
req.Headers.TryAddWithoutValidation("Authorization", $"Basic {auth}");

var res = await http.SendAsync(req);
var body = await res.Content.ReadAsStringAsync();
if (!res.IsSuccessStatusCode) throw new Exception($"HTTP {(int)res.StatusCode} - {body}");
Console.WriteLine(body);

Go (net/http)

package main

import (
  "encoding/base64"
  "fmt"
  "io"
  "net/http"
  "net/url"
  "os"
)

func main() {
  token := os.Getenv("BINDS_TOKEN")
  key := os.Getenv("BINDS_KEY")
  auth := base64.StdEncoding.EncodeToString([]byte(token + ":" + key))

  surveyId := "<surveyId>"
  u := "https://app.binds.co/api/survey-sendings?survey=" + url.QueryEscape(surveyId)

  req, _ := http.NewRequest("GET", u, nil)
  req.Header.Set("Authorization", "Basic "+auth)

  res, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer res.Body.Close()

  b, _ := io.ReadAll(res.Body)
  if res.StatusCode < 200 || res.StatusCode >= 300 {
    panic(fmt.Sprintf("HTTP %d - %s", res.StatusCode, string(b)))
  }
  fmt.Println(string(b))
}

Ruby (Net::HTTP)

require "net/http"
require "uri"
require "base64"

token = ENV["BINDS_TOKEN"]
key = ENV["BINDS_KEY"]
auth = Base64.strict_encode64("#{token}:#{key}")

survey_id = "<surveyId>"
uri = URI("https://app.binds.co/api/survey-sendings")
uri.query = URI.encode_www_form(survey: survey_id)

req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Basic #{auth}"

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
raise "HTTP #{res.code} - #{res.body}" unless res.code.to_i.between?(200, 299)
puts res.body

cURL (bash)

curl -X GET \
  "https://app.binds.co/api/survey-sendings?survey=<surveyId>" \
  -H "Authorization: Basic <base64(token:chave)>"

Precisa de ajuda para integrar?

Comece pelo Web Widget ou envie uma pesquisa via API para validar seu fluxo ponta a ponta.

Web Widget Criar conta

Integre com a binds.co via API

Introdução

Autenticação

Convenções da API

Exemplos por linguagem (mais usados)

Listar pesquisas

Listar coletores

Enviar pesquisa (seed)

Listar respostas

Listar abordagens