v1.0 Live

Documentație API Autocomplete & Coduri Poștale

RO EN

1. Autentificare & Securitate

Toate cererile către API-ul CeCodPostal necesită o cheie secretă, transmisă în header-ul X-API-KEY sau ca parametru api_key în URL. Cheile se pot genera direct din Panoul de Control B2B.

Metode de transmitere a cheii API:

Header (recomandat): X-API-KEY: ccp_live_YOUR_API_KEY

URL Query: https://cecodpostal.ro/api/v1/autocomplete?api_key=ccp_live_YOUR_API_KEY

GET /api/v1/autocomplete

2. Autocomplete Adrese & Smart Parsing

Algoritmul analizează automat șirurile brute scrise de clienți în checkout (ex: Bucuresti Sector 2 Ciurea 14 sau Constanta Mircea cel Batran 102) și extrage precis orașul, strada, numărul par/impar și codul poștal aferent.

Parametri Request (Query String)

Parametru	Tip	Obligatoriu	Descriere
q	String	Da (min 2 car)	Textul căutat (poate conține oraș, sector, stradă și număr într-un singur câmp).
localitate	String	Opțional	Filtrează strict după oraș/sector.
judet	String	Opțional	Filtrează după județ.
numar	String/Int	Opțional	Numărul străzii sau blocului pentru identificarea exactă a intervalului.

curl -X GET "https://cecodpostal.ro/api/v1/autocomplete?q=Bucuresti%20Sector%202%20Ciurea%2014" \
     -H "X-API-KEY: YOUR_API_KEY"

$response = Http::withHeaders(['X-API-KEY' => 'YOUR_API_KEY'])
    ->get('https://cecodpostal.ro/api/v1/autocomplete', [
        'q' => 'Bucuresti Sector 2 Ciurea 14'
    ]);

$data = $response->json();

const response = await fetch('https://cecodpostal.ro/api/v1/autocomplete?q=Bucuresti%20Sector%202%20Ciurea%2014', {
    headers: {
        'X-API-KEY': 'YOUR_API_KEY'
    }
});
const data = await response.json();
console.log(data);

import requests

headers = {'X-API-KEY': 'YOUR_API_KEY'}
params = {'q': 'Bucuresti Sector 2 Ciurea 14'}

response = requests.get('https://cecodpostal.ro/api/v1/autocomplete', headers=headers, params=params)
data = response.json()

3. Schema Obiectului JSON de Răspuns

Fiecare element din vectorul data conține informațiile necesare pentru completarea automată în checkout:

Câmp JSON	Tip	Descriere & Exemplu
strada_complet	String	Numele străzii împreună cu intervalul sau numărul fix. Ex: "Strada Ciurea nr. 12-T"
cod_postal	String	Codul poștal oficial din 6 cifre. Ex: "021926"
localitate	String	Numele orașului sau al sectorului. Ex: "Sector 2" sau "Constanta"
judet	String	Județul aferent adresei. Ex: "Bucuresti" sau "Constanta"

GET /api/v1/postcode/{code}

4. Căutare Strictă după Cod Poștal

Căutare directă pe baza codului poștal din 6 cifre. Utilizată pentru auto-completarea județului și localității atunci când clientul introduce doar codul.

GET https://cecodpostal.ro/api/v1/postcode/021926?api_key=YOUR_API_KEY

5. Integrare Rapidă: Drop-in JS Snippet

Puteți adăuga acest script direct în site-ul sau checkout-ul dvs. WooCommerce / custom pentru a adăuga autocomplete automat pe câmpul de adresă:

<!-- CeCodPostal.ro Autocomplete Snippet -->
<script>
  const CCP_API_KEY = 'ccp_live_YOUR_API_KEY';

  document.addEventListener('DOMContentLoaded', () => {
    const addressInput = document.querySelector('#billing_address_1') || document.querySelector('input[name="address"]');
    if (!addressInput) return;

    addressInput.addEventListener('input', async (e) => {
      const val = e.target.value;
      if (val.length < 3) return;

      try {
        const res = await fetch(`https://cecodpostal.ro/api/v1/autocomplete?q=${encodeURIComponent(val)}`, {
          headers: { 'X-API-KEY': CCP_API_KEY }
        });
        const data = await res.json();
        
        if (data.success && data.data.length > 0) {
          const item = data.data[0];
          // Auto-completare câmpuri checkout
          if (document.querySelector('#billing_postcode')) {
            document.querySelector('#billing_postcode').value = item.cod_postal;
          }
        }
      } catch (err) {
        console.error('CCP Autocomplete Error:', err);
      }
    });
  });
</script>

6. Coduri de Răspuns & Erori HTTP

Cod HTTP	Semnificație	Cauză / Soluție
200 OK	Succes	Interogarea a fost executată cu succes.
401 Unauthorized	Cheie lipsă	Nu ai trimis header-ul X-API-KEY și nici parametrul ?api_key=.
403 Forbidden	Cheie invalidă	Cheia API nu există sau contul este dezactivat.
404 Not Found	Cod inexistent	Nu există niciun rezultat pentru codul poștal căutat.
422 Unprocessable Entity	Format invalid	Codul poștal trebuie să conțină exact 6 cifre.
429 Too Many Requests	Limită depășită	Ai depășit limita de cereri (60/minut sau limita lunară a abonamentului).