v1.0 Live

Documentație API Autocomplete & Coduri Poștale

1. Autentificare & Securitate

Toate cererile către API-ul CeCodPostal necesită o cheie secretă de verificare de tip Bearer sau transmisă direct ca parametru în URL. Cheile se pot genera direct din Panoul de Control B2B.

Metode de transmitere a cheii API:

Header: Authorization: Bearer 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.
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 "Authorization: Bearer YOUR_API_KEY"

$response = Http::withToken('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: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});
const data = await response.json();
console.log(data);

import requests

headers = {'Authorization': 'Bearer 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_CHEIA_TA_AICI';

  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)}&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ă sau Inexistentă	Cheia API transmisă este invalidă sau revocată.
429 Too Many Requests	Limiă Depășită	Ai depășit rata maximă de cereri incluse în abonamentul tău.